From 92eff52c83efaa686efd9415ee00eba70f906514 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Sat, 29 Aug 2020 01:28:03 +0200 Subject: [PATCH 1/2] docs: consistent markup for OpenSSL and SSL, v9 OpenSSL was mostly referred to with the "productname" tag, but also with "application" as well without any markup at all. This moves to using "productname" for all mentions as well as using "acronym" on most mentions of SSL and its concepts. --- doc/src/sgml/config.sgml | 6 +++--- doc/src/sgml/libpq.sgml | 24 ++++++++++++------------ doc/src/sgml/pgcrypto.sgml | 8 ++++---- doc/src/sgml/sslinfo.sgml | 2 +- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 606e80df0e..032232e5d7 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1261,7 +1261,7 @@ include_dir 'conf.d' +3DES - The OpenSSL default order for HIGH is problematic + The OpenSSL default order for HIGH is problematic because it orders 3DES higher than AES128. This is wrong because 3DES offers less security than AES128, and it is also much slower. +3DES reorders it after all other @@ -1284,7 +1284,7 @@ include_dir 'conf.d' - Available cipher suite details will vary across OpenSSL versions. Use + Available cipher suite details will vary across OpenSSL versions. Use the command openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL' to see actual details for the currently installed OpenSSL @@ -1337,7 +1337,7 @@ include_dir 'conf.d' - OpenSSL names for the most common curves are: + OpenSSL names for the most common curves are: prime256v1 (NIST P-256), secp384r1 (NIST P-384), secp521r1 (NIST P-521). diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index a397073526..b932fdbaae 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -812,7 +812,7 @@ int callback_fn(char *buf, int size, PGconn *conn); its path will be in conn->sslkey when the callback is invoked. This will be empty if the default key path is being used. For keys that are engine specifiers, it is up to engine implementations - whether they use the OpenSSL password callback or define their own handling. + whether they use the OpenSSL password callback or define their own handling. @@ -1672,13 +1672,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Specifying this parameter with any non-empty value suppresses the Enter PEM pass phrase: - prompt that OpenSSL will emit by default when an encrypted client + prompt that OpenSSL will emit by default when an encrypted client certificate key is provided to libpq. If the key is not encrypted this parameter is ignored. The parameter has no - effect on keys specified by OpenSSL engines unless the engine uses the - OpenSSL password callback mechanism for prompts. + effect on keys specified by OpenSSL engines unless the engine uses the + OpenSSL password callback mechanism for prompts. There is no environment variable equivalent to this option, and no @@ -2471,8 +2471,8 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name); The struct(s) available depend on the SSL implementation in use. - For OpenSSL, there is one struct, available under the name "OpenSSL", - and it returns a pointer to the OpenSSL SSL struct. + For OpenSSL, there is one struct, available under the name "OpenSSL", + and it returns a pointer to the OpenSSL SSL struct. To use this function, code along the following lines could be used: @@ -2516,7 +2516,7 @@ void *PQgetssl(const PGconn *conn); This function is equivalent to PQsslStruct(conn, "OpenSSL"). It should not be used in new applications, because the returned struct is - specific to OpenSSL and will not be available if another SSL + specific to OpenSSL and will not be available if another SSL implementation is used. To check if a connection uses SSL, call instead, and for more details about the connection, use . @@ -7666,11 +7666,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) The key may be stored in cleartext or encrypted with a passphrase using any algorithm supported - by OpenSSL, like AES-128. If the key is stored encrypted, then the passphrase + by OpenSSL, like AES-128. If the key is stored encrypted, then the passphrase may be provided in the connection option. If an encrypted key is supplied and the sslpassword option is absent or blank, a password will be prompted for interactively by - OpenSSL with a Enter PEM pass phrase: + OpenSSL with a Enter PEM pass phrase: prompt if a TTY is available. Applications can override the client certificate prompt and the handling of the sslpassword parameter by supplying their own key password callback; see @@ -7936,7 +7936,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); When do_ssl is non-zero, libpq - will initialize the OpenSSL library before first + will initialize the OpenSSL library before first opening a database connection. When do_crypto is non-zero, the libcrypto library will be initialized. By default (if is not called), both libraries @@ -7945,7 +7945,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); - If your application uses and initializes either OpenSSL + If your application uses and initializes either OpenSSL or its underlying libcrypto library, you must call this function with zeroes for the appropriate parameter(s) before first opening a database connection. Also be sure that you @@ -7967,7 +7967,7 @@ void PQinitSSL(int do_ssl); This function is equivalent to PQinitOpenSSL(do_ssl, do_ssl). It is sufficient for applications that initialize both or neither - of OpenSSL and libcrypto. + of OpenSSL and libcrypto. diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index 6fd645aa70..36ba7b4041 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -45,7 +45,7 @@ digest(data bytea, type text) returns bytea sha224, sha256, sha384 and sha512. If pgcrypto was built with - OpenSSL, more algorithms are available, as detailed in + OpenSSL, more algorithms are available, as detailed in . @@ -1162,8 +1162,8 @@ gen_random_uuid() returns uuid - When compiled with OpenSSL, there will be more algorithms available. - Also public-key encryption functions will be faster as OpenSSL + When compiled with OpenSSL, there will be more algorithms available. + Also public-key encryption functions will be faster as OpenSSL has more optimized BIGNUM functions. @@ -1239,7 +1239,7 @@ gen_random_uuid() returns uuid - Any digest algorithm OpenSSL supports is automatically picked up. + Any digest algorithm OpenSSL supports is automatically picked up. This is not possible with ciphers, which need to be supported explicitly. diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml index 7d3fcb7167..195949f55a 100644 --- a/doc/src/sgml/sslinfo.sgml +++ b/doc/src/sgml/sslinfo.sgml @@ -174,7 +174,7 @@ This function returns the value of the specified field in the certificate subject, or NULL if the field is not present. Field names are string constants that are - converted into ASN1 object identifiers using the OpenSSL object + converted into ASN1 object identifiers using the OpenSSL object database. The following values are acceptable: -- 2.21.1 (Apple Git-122.3)