From 45cfab5980099ea0e25ae2e84e451331cf6b14b9 Mon Sep 17 00:00:00 2001 From: Karen Jex Date: Tue, 10 Nov 2026 17:09:48 +0100 Subject: [PATCH v2] Doc: standardise cleartext and plain text terms Replace variations of "plain text", plaintext, plain-text, "clear text", cleartext and clear-text with either "plain text" or cleartext depending on context. Use cleartext to refer to unencrypted data in storage or transmission. Use cleartext instead of plaintext because; it is consistent with the AuthenticationCleartextPassword server message, it is the term most used throughout the Postgres docs, and it is different enough from "plain text" not to cause confusion. Treat cleartext as a synonym for plaintext. Although not entirely accurate from a cryptography point of view, where plaintext is defined as the input to a data encrpytion algorythm or the output of a decryption process, the terms are used synonymously in many places, and are likely to be understood as synonyms by the majority of Postgres users. Use "plain text" to refer to unformatted, human-readable text. This was selected instead of the hyphenated plain-text because "plain text" is the standard form across the majority of technical documentation. This is the case even when it is used as an adjective, for example: "a plain text file". Rewrite sentences that contain the construct "non-plain-text" in order to remain consistent and avoid ambiguity. Add glossary entries to define the terms used. Author: Karen Jex Discussion: https://www.postgresql.org/message-id/CAOpR_fbRg0O_rsrkoJjnPe9aR7ChFuVgABe1rhwq%3D5EzPxt1GA%40mail.gmail.com --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/client-auth.sgml | 16 ++++++++-------- doc/src/sgml/config.sgml | 2 +- doc/src/sgml/dblink.sgml | 4 ++-- doc/src/sgml/docguide.sgml | 2 +- doc/src/sgml/func/func-trigger.sgml | 4 ++-- doc/src/sgml/glossary.sgml | 21 +++++++++++++++++++++ doc/src/sgml/libpq.sgml | 4 ++-- doc/src/sgml/maintenance.sgml | 2 +- doc/src/sgml/passwordcheck.sgml | 2 +- doc/src/sgml/pgcrypto.sgml | 8 ++++---- doc/src/sgml/postgres-fdw.sgml | 4 ++-- doc/src/sgml/protocol.sgml | 6 +++--- doc/src/sgml/ref/pg_dump.sgml | 11 ++++++----- doc/src/sgml/ref/pg_restore.sgml | 7 ++++--- doc/src/sgml/ref/psql-ref.sgml | 4 ++-- 16 files changed, 61 insertions(+), 38 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 78cce7e370d..942e7fbefee 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -8030,7 +8030,7 @@ SCRAM-SHA-256$<iteration count>:&l Access to the column subconninfo is revoked from - normal users, because it could contain plain-text passwords. + normal users, because it could contain cleartext passwords. diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 873ddd8f068..b7211b3cf71 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -549,7 +549,7 @@ include_dir directory Require the client to supply an unencrypted password for authentication. - Since the password is sent in clear text over the + Since the password is sent in cleartext over the network, this should not be used on untrusted networks. See for details. @@ -652,7 +652,7 @@ include_dir directory Authorize and optionally authenticate using a third-party OAuth 2.0 - identity provider. Since the bearer token is sent in clear text over + identity provider. Since the bearer token is sent in cleartext over the network, this should not be used on untrusted networks. See for details. @@ -1258,7 +1258,7 @@ omicron bryanh guest1 The method md5 uses a custom less secure challenge-response mechanism. It prevents password sniffing and avoids storing passwords - on the server in plain text but provides no protection if an attacker + on the server in cleartext but provides no protection if an attacker manages to steal the password hash from the server. Also, the MD5 hash algorithm is nowadays no longer considered secure against determined attacks. @@ -1286,7 +1286,7 @@ omicron bryanh guest1 password - The method password sends the password in clear-text and is + The method password sends the password in cleartext and is therefore vulnerable to password sniffing attacks. It should always be avoided if possible. If the connection is protected by SSL encryption then password can be used safely, though. @@ -1320,15 +1320,15 @@ omicron bryanh guest1 the scram-sha-256 setting, then it can be used for the authentication methods scram-sha-256 and password (but password transmission will be in - plain text in the latter case). The authentication method + cleartext in the latter case). The authentication method specification md5 will automatically switch to using the scram-sha-256 method in this case, as explained above, so it will also work. If a password was encrypted using the md5 setting, then it can be used only for the md5 and password authentication - method specifications (again, with the password transmitted in plain text + method specifications (again, with the password transmitted in cleartext in the latter case). (Previous PostgreSQL releases supported storing the - password on the server in plain text. This is no longer possible.) To + password on the server in cleartext. This is no longer possible.) To check the currently stored password hashes, see the system catalog pg_authid. @@ -2344,7 +2344,7 @@ host ... ldap ldapbasedn="dc=example,dc=net" which are a type of access token used with OAuth 2.0 where the token is an opaque string. The format of the access token is implementation specific and is chosen by each authorization server. The bearer token is sent - in clear-text, and is vulnerable to network sniffing. For this reason + in cleartext, and is vulnerable to network sniffing. For this reason OAuth should only be used over SSL connections. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index a6a2df177f2..a3f5f816356 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -8646,7 +8646,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' Logged statements might reveal sensitive data and even contain - plaintext passwords. + cleartext passwords. diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index fc496b74288..9120295d019 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -157,9 +157,9 @@ dblink_connect(text connname, text connstr) returns text authentication to connect to the remote database. It can be specified for a foreign server or a user mapping. A user mapping setting overrides the foreign server setting. With SCRAM pass-through authentication, - dblink uses SCRAM-hashed secrets instead of plain-text + dblink uses SCRAM-hashed secrets instead of cleartext user passwords to connect to the remote server. This avoids storing - plain-text user passwords in PostgreSQL system catalogs. + cleartext user passwords in PostgreSQL system catalogs. See the documentation of the equivalent use_scram_passthrough option of postgres_fdw for further details and restrictions. diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index a91b386817c..866f4a6ce51 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -30,7 +30,7 @@ - Additionally, a number of plain-text README files can + Additionally, a number of plain text README files can be found throughout the PostgreSQL source tree, documenting various implementation issues. diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml index 94b40adbdb8..a212fcadfc5 100644 --- a/doc/src/sgml/func/func-trigger.sgml +++ b/doc/src/sgml/func/func-trigger.sgml @@ -60,7 +60,7 @@ Automatically updates a tsvector column from associated - plain-text document column(s). The text search configuration to use + plain text document column(s). The text search configuration to use is specified by name as a trigger argument. See for details. @@ -79,7 +79,7 @@ Automatically updates a tsvector column from associated - plain-text document column(s). The text search configuration to use + plain text document column(s). The text search configuration to use is taken from a regconfig column of the table. See for details. diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index d28a3729188..c9f323d716f 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -434,6 +434,17 @@ + + Cleartext + + + Unencrypted data; data that exists in an unprotected, readable format + during storage or transmission. Sometimes used as a synonym for + plaintext; the input to an encryption algorithm. + + + + Client (process) @@ -1362,6 +1373,16 @@ + + Plain text + + + Unformatted, human-readable text that consists of a sequence of printable + characters in a character encoding such as UTF-8. + + + + Postmaster (process) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index b213a266cb2..3caaea91137 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1330,7 +1330,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname password - The server must request plaintext password authentication. + The server must request cleartext password authentication. @@ -1851,7 +1851,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname start SSL handshake directly after establishing the TCP/IP connection. This is only allowed with sslmode=require or higher, because the weaker - settings could lead to unintended fallback to plaintext + settings could lead to unintended fallback to cleartext authentication when the server does not support direct SSL handshake. diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml index e3f5cedd589..e3cc7ad01db 100644 --- a/doc/src/sgml/maintenance.sgml +++ b/doc/src/sgml/maintenance.sgml @@ -1291,7 +1291,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu The server log can contain sensitive information and needs to be protected, no matter how or where it is stored, or the destination to which it is routed. - For example, some DDL statements might contain plaintext passwords or other + For example, some DDL statements might contain cleartext passwords or other authentication details. Logged statements at the ERROR level might show the SQL source code for applications and might also contain some parts of data rows. Recording data, events and diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml index 7ea32410463..d8b061738e4 100644 --- a/doc/src/sgml/passwordcheck.sgml +++ b/doc/src/sgml/passwordcheck.sgml @@ -55,7 +55,7 @@ Alternatively, you could modify passwordcheck to reject pre-encrypted passwords, but forcing users to set their - passwords in clear text carries its own security risks. + passwords in cleartext carries its own security risks. diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index 00a35f3715c..b1ef6075e40 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -980,19 +980,19 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt created when the cipher-algo was unavailable under the OpenSSL configuration in use. Such faulty messages do not require the correct decryption key when ignore-cipher-failure is - enabled, so there is no guarantee that the decrypted plaintext actually + enabled, so there is no guarantee that the decrypted cleartext actually originated from a holder of the key. Contrast the case of a message which was correctly encrypted, but the cipher that produced it is unavailable under the current OpenSSL - configuration. Recovering such plaintext via pgcrypto + configuration. Recovering such cleartext via pgcrypto requires making the actual cipher available to OpenSSL by, for example, enabling the appropriate provider. ignore-cipher-failure is not necessary or helpful for that scenario. If decryption of a correctly encrypted message with this option happens to pass PGP integrity checks, that result is coincidental and does not make the - recovered plaintext trustworthy. + recovered cleartext trustworthy. Values: 0, 1 @@ -1338,7 +1338,7 @@ fips_mode() returns boolean All pgcrypto functions run inside the database server. That means that all the data and passwords move between pgcrypto and client - applications in clear text. Thus you must: + applications in cleartext. Thus you must: diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index 01577d8d69b..cab065405b2 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -815,8 +815,8 @@ OPTIONS (ADD password_required 'false'); A user mapping setting overrides the foreign server setting. With SCRAM pass-through authentication, postgres_fdw uses SCRAM-hashed secrets instead of - plain-text user passwords to connect to the remote server. This - avoids storing plain-text user passwords in PostgreSQL system + cleartext user passwords to connect to the remote server. This + avoids storing cleartext user passwords in PostgreSQL system catalogs. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 541673eb282..50ce1cbdb32 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -471,7 +471,7 @@ The frontend must now send a PasswordMessage containing the - password in clear-text form. If + password in cleartext form. If this is the correct password, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. @@ -2087,7 +2087,7 @@ SELCT 1/0; The bearer token is sent across the connection, as part of the client - initial response, and grants access to the database like a clear-text + initial response, and grants access to the database like a cleartext password. On an unencrypted connection it can be captured by network sniffing. For this reason OAUTHBEARER should only be used over SSL connections. @@ -3923,7 +3923,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32(3) - Specifies that a clear-text password is required. + Specifies that a cleartext password is required. diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 774be23b4f9..75e76f676c1 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -56,7 +56,7 @@ PostgreSQL documentation Dumps can be output in script or archive file formats. Script - dumps are plain-text files containing the SQL commands required + dumps are plain text files containing the SQL commands required to reconstruct the database to the state it was in at the time it was saved. To restore from such a script, feed it to . Script files @@ -101,7 +101,8 @@ PostgreSQL documentation Restoring a dump causes the destination to execute arbitrary code of the source superusers' choice. Partial dumps and partial restores do not limit that. If the source superusers are not trusted, the dumped SQL statements - must be inspected before restoring. Non-plain-text dumps can be inspected + must be inspected before restoring. Dumps in formats other than plain + text can be inspected by using pg_restore's option. Note that the client running the dump and restore need not trust the source or destination superusers. @@ -315,7 +316,7 @@ PostgreSQL documentation plain - Output a plain-text SQL script file (the default). + Output a plain text SQL script file (the default). @@ -1236,7 +1237,7 @@ PostgreSQL documentation Use the provided string as the psql \restrict key in the dump output. This can only be - specified for plain-text dumps, i.e., when is + specified for plain text dumps, i.e., when is set to plain or the option is omitted. If no restrict key is specified, pg_dump will generate a random one as @@ -1740,7 +1741,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; It is generally recommended to use the () option when restoring a database from a - plain-text pg_dump script to ensure a clean + plain text pg_dump script to ensure a clean restore process and prevent potential conflicts with non-default psql configurations. diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 98d7456e83b..bff18277c2b 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -39,8 +39,8 @@ PostgreSQL documentation pg_restore is a utility for restoring a PostgreSQL database from an archive - created by in one of the non-plain-text - formats. It will issue the commands necessary to reconstruct the + created by in a format other than plain text. + It will issue the commands necessary to reconstruct the database to the state it was in at the time it was saved. The archive files also allow pg_restore to be selective about what is restored, or even to reorder the items @@ -74,7 +74,8 @@ PostgreSQL documentation Restoring a dump causes the destination to execute arbitrary code of the source superusers' choice. Partial dumps and partial restores do not limit that. If the source superusers are not trusted, the dumped SQL statements - must be inspected before restoring. Non-plain-text dumps can be inspected + must be inspected before restoring. Dumps in formats other than plain + text can be inspected by using pg_restore's option. Note that the client running the dump and restore need not trust the source or destination superusers. diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 4058caf061b..b0f86e931ab 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -3587,7 +3587,7 @@ SELECT $1 \parse stmt1 restricted mode. The key may contain only alphanumeric characters. - This command is primarily intended for use in plain-text dumps + This command is primarily intended for use in plain text dumps generated by pg_dump, pg_dumpall, and pg_restore, but it may be useful elsewhere. @@ -3856,7 +3856,7 @@ SELECT 1 \bind \sendpipeline \restrict when restricted mode was entered. - This command is primarily intended for use in plain-text dumps + This command is primarily intended for use in plain text dumps generated by pg_dump, pg_dumpall, and pg_restore, but it may be useful elsewhere. -- 2.50.1 (Apple Git-155)