Clarify the PKCS12 docs

Issue #23151 asks a question about the meaning of the PKCS12
documentation. This PR attempts to clarify how friendlyName and localKeyID
are added to the PKCS12 structure.

Fixes #23151

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
(Merged from https://github.com/openssl/openssl/pull/23188)

(cherry picked from commit 3348713ad390372ba5a0a0f98b46b2f637475e47)

diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod
index 92e588062a36ed3a085c1246c749b152801cc036..9d5403113aea1f64acb5c53cfaf066a76667a1c4 100644 (file)
--- a/doc/man3/PKCS12_create.pod
+++ b/doc/man3/PKCS12_create.pod
@@ -57,9 +57,15 @@ export grade software which could use signing only keys of arbitrary size but
 had restrictions on the permissible sizes of keys which could be used for
 encryption.
 
-If a certificate contains an I<alias> or I<keyid> then this will be
-used for the corresponding B<friendlyName> or B<localKeyID> in the
-PKCS12 structure.
+If I<name> is B<NULL> and I<cert> contains an I<alias> then this will be
+used for the corresponding B<friendlyName> in the PKCS12 structure instead.
+Similarly, if I<pkey> is NULL and I<cert> contains a I<keyid> then this will be
+used for the corresponding B<localKeyID> in the PKCS12 structure instead of the
+id calculated from the I<pkey>.
+
+For all certificates in I<ca> then if a certificate contains an I<alias> or
+I<keyid> then this will be used for the corresponding B<friendlyName> or
+B<localKeyID> in the PKCS12 structure.
 
 Either I<pkey>, I<cert> or both can be B<NULL> to indicate that no key or
 certificate is required. In previous versions both had to be present or