Le ven. 6 nov. 2026 à 20:16, Karen Jex <[email protected]> a écrit :

> I see that the cleartext Wikipedia entry redirects to plaintext:
> https://en.wikipedia.org/wiki/Plaintext, which implies that plaintext
> may be the preferred term.

I originally thought we should standardise on "plaintext", but after
reviewing the ways in which the terms are used throughout the docs, I
propose the following approach:

1. Use "plain text" to indicate unformatted text: e.g. "...a plain
text file with special syntax that translators edit."
(https://www.postgresql.org/docs/devel/nls-translator.html#NLS-TRANSLATOR-CONCEPTS).

2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
is good practice not to send the original cleartext password..."
(https://www.postgresql.org/docs/devel/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN).
This is consistent with the AuthenticationCleartextPassword server
message referenced on the same page.

This is consistent with the vocabulary that is used most often in the
documentation, and the terms are different enough to avoid
confusion/ambiguity.

I attach the proposed patch and, for completeness, a csv file that
lists the proposed changes. I would be very grateful for any feedback
before I submit it to -hackers.

--
Karen
File,Term,URL,Text containing the term,Change Required
doc/src/sgml/arch-dev.sgml,plain text,https://www.postgresql.org/docs/devel/connect-estab.html,"The query is transmitted using plain text, i.e., there is no parsing done in the client.",No change
doc/src/sgml/arch-dev.sgml,plain text,https://www.postgresql.org/docs/devel/parser-stage.html,The parser has to check the query string (which arrives as plain text) for valid syntax.,No change
doc/src/sgml/catalogs.sgml,plain-text,https://www.postgresql.org/docs/devel/catalog-pg-subscription.html,...it could contain plain-text passwords.,Change to cleartext
doc/src/sgml/client-auth.sgml,clear text,https://www.postgresql.org/docs/devel/auth-pg-hba-conf.html,...the password is sent in clear text over the network...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear text,https://www.postgresql.org/docs/devel/auth-pg-hba-conf.html,...the bearer token is sent in clear text over the network...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear-text,https://www.postgresql.org/docs/devel/auth-oauth.html,The bearer token is sent in clear-text...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear-text,https://www.postgresql.org/docs/devel/auth-password.html,...sends the password in clear-text...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...avoids storing passwords on the server in plain text...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...password transmission will be in plain text in the latter case...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,"...again, with the password transmitted in plain text in the latter case...",Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...storing the password on the server in plain text.,Change to cleartext
doc/src/sgml/config.sgml,plaintext,https://www.postgresql.org/docs/devel/runtime-config-logging.html,...might reveal sensitive data and even contain plaintext passwords,Change to cleartext
doc/src/sgml/datatype.sgml,plain text,https://www.postgresql.org/docs/devel/datatype-net-types.html,...better to use these types instead of plain text types to store network addresses...,No change
doc/src/sgml/dblink.sgml,plain-text,https://www.postgresql.org/docs/devel/contrib-dblink-connect.html,...uses SCRAM-hashed secrets instead of plain-text user passwords...,Change to cleartext
doc/src/sgml/dblink.sgml,plain-text,https://www.postgresql.org/docs/devel/contrib-dblink-connect.html,This avoids storing plain-text user passwords in...,Change to cleartext
doc/src/sgml/docguide.sgml,plain text,https://www.postgresql.org/docs/devel/docguide.html,"PostgreSQL has four primary documentation formats ... Plain text, for pre-installation information",No change
doc/src/sgml/docguide.sgml,plain-text,https://www.postgresql.org/docs/devel/docguide.html,...a number of plain-text README files...,Change to plain text
doc/src/sgml/func/func-trigger.sgml,plain-text,https://www.postgresql.org/docs/devel/functions-trigger.html,...column from associated plain-text document column(s).,Change to plain text
doc/src/sgml/func/func-trigger.sgml,plain-text,https://www.postgresql.org/docs/devel/functions-trigger.html,...column from associated plain-text document column(s).,Change to plain text
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-connect.html,...makes the destination host name appear in cleartext in the network traffic...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...good practice not to send the original cleartext password...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...the cleartext password...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...the new cleartext password.,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-ssl.html,The key may be stored in cleartext or encrypted...,No change
doc/src/sgml/libpq.sgml,plaintext,https://www.postgresql.org/docs/devel/libpq-connect.html,The server must request plaintext password authentication.,Change to cleartext
doc/src/sgml/libpq.sgml,plaintext,https://www.postgresql.org/docs/devel/libpq-connect.html,...fallback to plaintext authentication...,Change to cleartext
doc/src/sgml/logical-replication.sgml,plain text,https://www.postgresql.org/docs/devel/logical-replication-subscription.html,"Conflicts that occur during replication are, by default, logged as plain text in the server log",No change
doc/src/sgml/maintenance.sgml,plaintext,https://www.postgresql.org/docs/devel/logfile-maintenance.html,...some DDL statements might contain plaintext passwords...,Change to cleartext
doc/src/sgml/nls.sgml,plain text,https://www.postgresql.org/docs/devel/nls-translator.html,...a plain text file with special syntax...,No change
doc/src/sgml/passwordcheck.sgml,clear text,https://www.postgresql.org/docs/devel/passwordcheck.html,...forcing users to set their passwords in clear text...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,clear text,https://www.postgresql.org/docs/devel/pgcrypto.html,...passwords move between pgcrypto and client applications in clear text...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,...guarantee that the decrypted plaintext actually originated from...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,Recovering such plaintext via pgcrypto requires...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,...does not make the recovered plaintext trustworthy.,Change to cleartext
doc/src/sgml/postgres-fdw.sgml,plain-text,https://www.postgresql.org/docs/devel/postgres-fdw.html,...instead of plain-text user passwords to connect to the remote server.  ,Change to cleartext
doc/src/sgml/postgres-fdw.sgml,plain-text,https://www.postgresql.org/docs/devel/postgres-fdw.html,This avoids storing plain-text user passwords...,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/protocol-flow.html,...PasswordMessage containing the password in clear-text form.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/protocol-message-formats.html,Specifies that a clear-text password is required.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/sasl-authentication.html,...like a clear-text password.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,www.postgresql.org/docs/devel/protocol-flow.html,...containing the password in clear-text form.,Change to cleartext
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-flow.html,<term>AuthenticationCleartextPassword</term>,No change
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-message-formats.html,";<varlistentry id=""protocol-message-formats-AuthenticationCleartextPassword"">",No change
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-message-formats.html,<term>AuthenticationCleartextPassword (B)</term>,No change
doc/src/sgml/ref/alter_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-alterrole.html,The password will be transmitted to the server in cleartext...,No change
doc/src/sgml/ref/alter_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-alterrole.html,without exposing the cleartext password...,No change
doc/src/sgml/ref/create_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-createrole.html,The password will be transmitted to the server in cleartext...,No change
doc/src/sgml/ref/pg_dump.sgml,plain text,https://www.postgresql.org/docs/devel/app-pgdump.html,For plain text output...,No change
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,This can only be specified for plain-text dumps...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,...when restoring a database from a plain-text pg_dump script...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,...dumps are plain-text files...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,Output a plain-text SQL script file...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,Non-plain-text dumps...,Change to plain text
doc/src/sgml/ref/pg_restore.sgml,plain text,https://www.postgresql.org/docs/devel/app-pgrestore.html,...is equivalent to the plain text output format...,No change
doc/src/sgml/ref/pg_restore.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgrestore.html,one of the non-plain-text formats,Change to plain text
doc/src/sgml/ref/pg_restore.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgrestore.html,Non-plain-text dumps,Change to plain text
doc/src/sgml/ref/psql-ref.sgml,cleartext,https://www.postgresql.org/docs/devel/app-psql.html,...the new password does not appear in cleartext...,No change
doc/src/sgml/ref/psql-ref.sgml,plain-text,https://www.postgresql.org/docs/devel/app-psql.html,...for use in plain-text dumps...,Change to plain text
doc/src/sgml/ref/psql-ref.sgml,plain-text,https://www.postgresql.org/docs/devel/app-psql.html,...for use in plain-text dumps...,Change to plain text
doc/src/sgml/sources.sgml,plain text,https://www.postgresql.org/docs/devel/source-format.html,...will re-flow indented comment blocks as though they were plain text.,No change
doc/src/sgml/uuid-ossp.sgml,cleartext,https://www.postgresql.org/docs/devel/uuid-ossp.html,"The name parameter will be MD5-hashed, so the cleartext cannot be derived from the generated UUID.",No change

Attachment: v1-0001-Doc-standardise-cleartext-and-plain-text-terms.patch
Description: Binary data

Reply via email to