From: Matt Caswell <matt@openssl.org>
Date: Wed, 3 Jan 2024 11:03:03 +0000 (+0000)
Subject: Clarify the PKCS12 docs
X-Git-Tag: openssl-3.1.5~52
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1a51185ceef2561efd0c33af0244600e1dbac149;p=thirdparty%2Fopenssl.git

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 92e588062a3..9d5403113ae 100644
--- 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