Commit 39c0fe5984 for openssl.org

commit 39c0fe5984819b76c03499ede87ac72fba9803e0
Author: Dr. David von Oheimb <David.von.Oheimb@siemens.com>
Date:   Sat Nov 26 10:33:53 2022 +0100

    X509_check_issued.pod: add doc of X509_check_akid(), complete X509_check_issued()

    Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
    Reviewed-by: Tomas Mraz <tomas@openssl.org>
    MergeDate: Wed Mar 11 11:22:30 2026
    (Merged from https://github.com/openssl/openssl/pull/28373)

diff --git a/doc/man3/X509_check_issued.pod b/doc/man3/X509_check_issued.pod
index e5339fe3d5..3d82ce56c1 100644
--- a/doc/man3/X509_check_issued.pod
+++ b/doc/man3/X509_check_issued.pod
@@ -2,37 +2,69 @@

 =head1 NAME

-X509_check_issued - checks if certificate is apparently issued by another
-certificate
+X509_check_issued, X509_check_akid
+- helper functions to check whether one certificate is a potential issuer of another certificate

 =head1 SYNOPSIS

  #include <openssl/x509v3.h>

  int X509_check_issued(const X509 *issuer, const X509 *subject);
-
+ int X509_check_akid(const X509 *issuer, const AUTHORITY_KEYID *akid);

 =head1 DESCRIPTION

 X509_check_issued() checks if certificate I<subject> was apparently issued
-using (CA) certificate I<issuer>. This function takes into account not only
-matching of the issuer field of I<subject> with the subject field of I<issuer>,
-but also compares all sub-fields of the B<authorityKeyIdentifier> extension of
+using (CA) certificate I<issuer>. It checks if the issuer field of I<subject>
+equals the subject field of I<issuer>. Moreover, it compares using
+X509_check_akid() all sub-fields of the B<authorityKeyIdentifier> extension of
 I<subject>, as far as present, with the respective B<subjectKeyIdentifier>,
 serial number, and issuer fields of I<issuer>, as far as present. It also checks
-if the B<keyUsage> field (if present) of I<issuer> allows certificate signing.
+if the I<subject> signature algorithm matches the I<issuer> public key algorithm
+and if any B<keyUsage> field given in I<issuer> allows certificate signing.
 It does not actually check the certificate signature. An error is returned
 if the I<issuer> or the I<subject> are incomplete certificates.

+X509_check_akid() is a more low-level function.
+It assumes that various internal fields of I<issuer> have already been filled in,
+for instance by calling L<X509_check_purpose(3)> with its I<id> parameter being -1.
+It checks whether the fields of the subject certificate's authority key identifier I<akid>,
+match the corresponding fields of the I<issuer> certificate.
+In more detail:
+It returns B<X509_V_OK> if I<akid> is NULL (because this means no restriction)
+or all the following conditions are met:
+
+=over 4
+
+=item *
+
+if I<akid> has the C<keyIdentifier> field,
+its value matches the B<subjectKeyIdentifier> (SKID) extension of I<issuer> if present,
+
+=item *
+
+if I<akid> has the C<authorityCertSerialNumber> field,
+its value equals the serial number of the I<issuer> certificate, and
+
+=item *
+
+if I<akid> has the C<authorityCertIssuer> field
+and its C<GeneralNames> include at least one C<directoryName>,
+the first such name equals the C<issuer> field of the I<issuer> certificate.
+
+=back
+
+
 =head1 RETURN VALUES

-X509_check_issued() returns B<X509_V_OK> if all checks are successful
-or some B<X509_V_ERR*> constant to indicate an error.
+X509_check_issued() and X509_check_akid()
+return B<X509_V_OK> if all checks are successful
+or some B<X509_V_ERR*> constant indicating why the issuer does not match.

 =head1 SEE ALSO

 L<X509_verify_cert(3)>, L<X509_verify(3)>, L<X509_check_ca(3)>,
-L<openssl-verify(1)>, L<X509_self_signed(3)>
+L<openssl-verify(1)>, L<X509_self_signed(3)>, L<X509_check_purpose(3)>

 =head1 HISTORY

diff --git a/doc/man3/X509_check_purpose.pod b/doc/man3/X509_check_purpose.pod
index 721c8345a2..8828207955 100644
--- a/doc/man3/X509_check_purpose.pod
+++ b/doc/man3/X509_check_purpose.pod
@@ -62,6 +62,8 @@ Below are the potential ID's that can be checked:
 The checks performed take into account the X.509 extensions
 keyUsage, extendedKeyUsage, and basicConstraints.

+No actual check is performed if I<id> is -1.
+
 X509_PURPOSE_get_count() returns the number of currently defined purposes.

 X509_PURPOSE_get_unused_id() returns the smallest purpose id not yet used,
@@ -99,6 +101,11 @@ X509_PURPOSE_set() assigns the given I<purpose> id to the location pointed at by
 I<p>.
 This resets to the any purpose if I<purpose> is B<X509_PURPOSE_DEFAULT_ANY>.

+=head1 NOTES
+
+X509_check_purpose() fills in various internal fields of the certificate structure I<x>.
+This is safe despite the I<x> argument's type change to I<const X509 *> as of OpenSSL 4.0.
+
 =head1 RETURN VALUES

 X509_check_purpose() returns the following values.
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 6a021ace14..8a33202a20 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -1150,7 +1150,6 @@ X509_alias_set1(3)
 X509_aux_print(3)
 X509_certificate_type(3)
 X509_chain_check_suiteb(3)
-X509_check_akid(3)
 X509_check_trust(3)
 X509_email_free(3)
 X509_find_by_issuer_and_serial(3)