Add X509V3_set_issuer_pkey, needed for AKID of self-issued not self-signed cert

Also clean up some related auxiliary functions and documentation

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13658)

5 files changed, 89 insertions, 58 deletions

diff --git a/doc/internal/man3/s2i_ASN1_UTF8STRING.pod b/doc/internal/man3/s2i_ASN1_UTF8STRING.pod
deleted file mode 100644
index b6d1375189..0000000000
--- a/doc/internal/man3/s2i_ASN1_UTF8STRING.pod
+++ /dev/null
@@ -1,46 +0,0 @@
-=pod
-
-=head1 NAME
-
-i2s_ASN1_UTF8STRING,
-s2i_ASN1_UTF8STRING
-- convert objects from/to ASN.1/string representation
-
-=head1 SYNOPSIS
-
- #include "crypto/x509v3.h"
-
- char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
-                           ASN1_UTF8STRING *utf8);
- ASN1_UTF8STRING *s2i_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
-                                      X509V3_CTX *ctx, const char *str);
-
-=head1 DESCRIPTION
-
-These functions convert OpenSSL objects to and from their ASN.1/string
-representation. This function is used for B<X509v3> extensions.
-
-=head1 NOTES
-
-The letters B<i> and B<s> in i2s_ASN1_UTF8STRING() stand for
-"internal" (that is, an internal C structure) and string respectively.
-So B<i2s_ASN1_UTF8STRING>() converts from internal to string.
-
-=head1 RETURN VALUES
-
-B<s2i_ASN1_UTF8STRING>() return a valid
-B<ASN1_UTF8STRING> structure or NULL if an error occurs.
-
-B<i2s_ASN1_UTF8STRING>() returns the pointer to a UTF-8 string
-or NULL if an error occurs.
-
-=head1 COPYRIGHT
-
-Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man3/ASN1_generate_nconf.pod b/doc/man3/ASN1_generate_nconf.pod
index a507e444c6..8b195d523f 100644
--- a/doc/man3/ASN1_generate_nconf.pod
+++ b/doc/man3/ASN1_generate_nconf.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
+ASN1_generate_nconf, ASN1_generate_v3 - ASN1 string generation functions
 
 =head1 SYNOPSIS
 
@@ -16,10 +16,10 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
 These functions generate the ASN1 encoding of a string
 in an B<ASN1_TYPE> structure.
 
-I<str> contains the string to encode I<nconf> or I<cnf> contains
+I<str> contains the string to encode. I<nconf> or I<cnf> contains
 the optional configuration information where additional strings
 will be read from. I<nconf> will typically come from a config
-file whereas I<cnf> is obtained from an B<X509V3_CTX> structure
+file whereas I<cnf> is obtained from an B<X509V3_CTX> structure,
 which will typically be used by X509 v3 certificate extension
 functions. I<cnf> or I<nconf> can be set to NULL if no additional
 configuration will be used.
diff --git a/doc/man3/X509V3_set_ctx.pod b/doc/man3/X509V3_set_ctx.pod
new file mode 100644
index 0000000000..136e3f1982
--- /dev/null
+++ b/doc/man3/X509V3_set_ctx.pod
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+X509V3_set_ctx,
+X509V3_set_issuer_pkey - X.509v3 extension generation utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject,
+                     X509_REQ *req, X509_CRL *crl, int flags);
+ int X509V3_set_issuer_pkey(X509V3_CTX *ctx, EVP_PKEY *pkey);
+
+=head1 DESCRIPTION
+
+X509V3_set_ctx() fills in the basic fields of I<ctx> of type B<X509V3_CTX>,
+providing details potentially needed by functions producing X509 v3 certificate
+extensions, e.g., to look up values for filling in authority key identifiers.
+Any of I<subj>, I<req>, or I<crl> may be provided, pointing to a certificate,
+certification request, or certificate revocation list, respectively.
+If I<subj> or I<crl> is provided, I<issuer> should point to its issuer,
+for instance to help generating an authority key identifier extension.
+Note that if I<subj> is provided, I<issuer> may be the same as I<subj>,
+which means that I<subj> is self-issued (or even self-signed).
+I<flags> may be 0 or contain B<CTX_TEST>, which means that just the syntax of
+extension definitions is to be checked without actually producing an extension,
+or B<X509V3_CTX_REPLACE>, which means that each X.509v3 extension added as
+defined in some configuration section shall replace any already existing
+extension with the same OID.
+
+X509V3_set_issuer_pkey() explicitly sets the issuer private key of
+the certificate that has been provided in I<ctx>.
+This should be done for self-issued certificates (which may be self-signed
+or not) to provide fallback data for the authority key identifier extension.
+
+=head1 RETURN VALUES
+
+X509V3_set_ctx() and X509V3_set_issuer_pkey()
+return 1 on success and 0 on error.
+
+=head1 SEE ALSO
+
+L<X509_add_ext(3)>
+
+=head1 HISTORY
+
+X509V3_set_issuer_pkey() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/s2i_ASN1_IA5STRING.pod b/doc/man3/s2i_ASN1_IA5STRING.pod
index e59a85606b..5215b6a179 100644
--- a/doc/man3/s2i_ASN1_IA5STRING.pod
+++ b/doc/man3/s2i_ASN1_IA5STRING.pod
@@ -10,11 +10,13 @@ i2s_ASN1_OCTET_STRING,
 s2i_ASN1_OCTET_STRING,
 i2s_ASN1_ENUMERATED,
 i2s_ASN1_ENUMERATED_TABLE,
+i2s_ASN1_UTF8STRING,
+s2i_ASN1_UTF8STRING
 - convert objects from/to ASN.1/string representation
 
 =head1 SYNOPSIS
 
-=for openssl generic
+ #include <openssl/x509v3.h>
 
  char *i2s_ASN1_IA5STRING(X509V3_EXT_METHOD *method, ASN1_IA5STRING *ia5);
  ASN1_IA5STRING *s2i_ASN1_IA5STRING(X509V3_EXT_METHOD *method,
@@ -29,6 +31,11 @@ i2s_ASN1_ENUMERATED_TABLE,
  char *i2s_ASN1_ENUMERATED_TABLE(X509V3_EXT_METHOD *method,
                                 const ASN1_ENUMERATED *e);
 
+ char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
+                           ASN1_UTF8STRING *utf8);
+ ASN1_UTF8STRING *s2i_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
+                                      X509V3_CTX *ctx, const char *str);
+
 =head1 DESCRIPTION
 
 These functions convert OpenSSL objects to and from their ASN.1/string
@@ -36,7 +43,7 @@ representation. This function is used for B<X509v3> extensions.
 
 =head1 NOTES
 
-The letters B<i> and B<s> in B<i2s_ASN1_IA5STRING>() stand for
+The letters B<i> and B<s> in B<i2s> and B<s2i> stand for
 "internal" (that is, an internal C structure) and string respectively.
 So B<i2s_ASN1_IA5STRING>() converts from internal to string.
 
@@ -70,6 +77,16 @@ string or NULL if an error occurs.
 B<s2i_ASN1_ENUMERATED>() returns the pointer to a B<ASN1_ENUMERATED>
 structure or NULL if an error occurs.
 
+B<s2i_ASN1_UTF8STRING>() return a valid
+B<ASN1_UTF8STRING> structure or NULL if an error occurs.
+
+B<i2s_ASN1_UTF8STRING>() returns the pointer to a UTF-8 string
+or NULL if an error occurs.
+
+=head1 HISTORY
+
+i2s_ASN1_UTF8STRING() and s2i_ASN1_UTF8STRING() were made public in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod
index b2ee41b853..c15a1d0ce0 100644
--- a/doc/man5/x509v3_config.pod
+++ b/doc/man5/x509v3_config.pod
@@ -169,7 +169,7 @@ Examples:
 =head2 Subject Key Identifier
 
 The SKID extension specification has a value with three choices.
-If the value is the word B<none>, then no SKID extension will be included.
+If the value is the word B<none> then no SKID extension will be included.
 If the value is the word B<hash>, or by default for the B<x509>, B<req>, and
 B<ca> apps, the process specified in RFC 5280 section 4.2.1.2. (1) is followed:
 The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT
@@ -193,14 +193,14 @@ indicated by putting a colon C<:> between the value and this option.
 By default the B<x509>, B<req>, and B<ca> apps behave as if
 "none" was given for self-signed certificates and "keyid, issuer" otherwise.
 
-If B<keyid> is present, an attempt is made to copy the subject key identifier
-(SKID) from the issuer certificate, which is the default behavior.
+If B<keyid> is present, an attempt is made to compute the hash of the public key
+corresponding to the signing key in case the certificate is self-signed,
+or else to copy the subject key identifier (SKID) from the issuer certificate.
 If this fails and the option B<always> is present, an error is returned.
-For self-issued certs the specification for the SKID must be given before.
 
-If B<issuer> is present and no B<keyid> has been added
-or it has the option B<always> specified, then
-the issuer DN and serial number are copied from the issuer certificate.
+If B<issuer> is present, and in addition it has the option B<always> specified
+or B<keyid> is not present,
+then the issuer DN and serial number are copied from the issuer certificate.
 
 Examples: