diff options
Diffstat (limited to 'doc/man3/OSSL_CMP_ITAV_new_caCerts.pod')
| -rw-r--r-- | doc/man3/OSSL_CMP_ITAV_new_caCerts.pod | 101 |
1 files changed, 95 insertions, 6 deletions
diff --git a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod index 66f0ac9030..209c56929e 100644 --- a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod +++ b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod @@ -7,7 +7,14 @@ OSSL_CMP_ITAV_get0_caCerts, OSSL_CMP_ITAV_new_rootCaCert, OSSL_CMP_ITAV_get0_rootCaCert, OSSL_CMP_ITAV_new_rootCaKeyUpdate, -OSSL_CMP_ITAV_get0_rootCaKeyUpdate +OSSL_CMP_ITAV_get0_rootCaKeyUpdate, +OSSL_CMP_CRLSTATUS_new1, +OSSL_CMP_CRLSTATUS_create, +OSSL_CMP_CRLSTATUS_get0, +OSSL_CMP_ITAV_new0_crlStatusList, +OSSL_CMP_ITAV_get0_crlStatusList, +OSSL_CMP_ITAV_new_crls, +OSSL_CMP_ITAV_get0_crls - CMP utility functions for handling specific genm and genp messages =head1 SYNOPSIS @@ -27,6 +34,21 @@ OSSL_CMP_ITAV_get0_rootCaKeyUpdate X509 **newWithOld, X509 **oldWithNew); + OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_new1(const DIST_POINT_NAME *dpn, + const GENERAL_NAMES *issuer, + const ASN1_TIME *thisUpdate); + OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_create(const X509_CRL *crl, + const X509 *cert, int only_DN); + int OSSL_CMP_CRLSTATUS_get0(const OSSL_CMP_CRLSTATUS *crlstatus, + DIST_POINT_NAME **dpn, GENERAL_NAMES **issuer, + ASN1_TIME **thisUpdate); + OSSL_CMP_ITAV + *OSSL_CMP_ITAV_new0_crlStatusList(STACK_OF(OSSL_CMP_CRLSTATUS) *crlStatusList); + int OSSL_CMP_ITAV_get0_crlStatusList(const OSSL_CMP_ITAV *itav, + STACK_OF(OSSL_CMP_CRLSTATUS) **out); + OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_crls(const X509_CRL *crl); + int OSSL_CMP_ITAV_get0_crls(const OSSL_CMP_ITAV *itav, STACK_OF(X509_CRL) **out); + =head1 DESCRIPTION ITAV is short for InfoTypeAndValue. @@ -49,6 +71,8 @@ the internal pointer to the certificate contained in the infoValue field. OSSL_CMP_ITAV_new_rootCaKeyUpdate() creates a new B<OSSL_CMP_ITAV> structure of type B<rootCaKeyUpdate> that includes an RootCaKeyUpdateContent structure with the optional I<newWithNew>, I<newWithOld>, and I<oldWithNew> certificates. +An RootCaKeyUpdateContent structure is included only if I<newWithNew> +is not NULL. OSSL_CMP_ITAV_get0_rootCaKeyUpdate() requires that I<itav> has infoType B<rootCaKeyUpdate>. @@ -59,7 +83,64 @@ If I<newWithOld> is not NULL, it assigns to I<*newWithOld> the internal pointer to the certificate contained in the newWithOld infoValue sub-field of I<itav>. If I<oldWithNew> is not NULL, it assigns to I<*oldWithNew> the internal pointer to the certificate contained in the oldWithNew infoValue sub-field of I<itav>. -Each of these pointers will be NULL if the respective sub-field is not set. +Each of these pointers will be set to NULL if no root CA certificate update +is present or the respective sub-field is not included. + +OSSL_CMP_CRLSTATUS_new1() allocates a new B<OSSL_CMP_CRLSTATUS> structure +that contains either a copy of the distribution point name I<dpn> +or a copy of the certificate issuer I<issuer>, while giving both is an error. +If given, a copy of the CRL issuance time I<thisUpdate> is also included. + +OSSL_CMP_CRLSTATUS_create() is a high-level variant of OSSL_CMP_CRLSTATUS_new1(). +It fills the thisUpdate field with a copy of the thisUpdate field of I<crl> if present. +It fills the CRLSource field with a copy of the first data item found using the I<crl> +and/or I<cert> parameters as follows. +Any available distribution point name is preferred over issuer names. +Data from I<cert>, if present, is preferred over data from I<crl>. +If no distribution point names are available, +candidate issuer names are taken from following sources, as far as present: + +=over 4 + +=item the list of distribution points in the first cRLDistributionPoints +extension of I<cert>, + +=item the issuer field of the authority key identifier of I<cert>, + +=item the issuer DN of I<cert>, + +=item the issuer field of the authority key identifier of I<crl>, and + +=item the issuer DN of I<crl>. + +=back + +If <only_DN> is set, a candidate issuer name of type B<GENERAL_NAMES> is +accepted only if it contains exactly one general name of type directoryName. + +OSSL_CMP_CRLSTATUS_get0() reads the fields of I<crlstatus> +and assigns them to I<*dpn>, I<*issuer>, and I<*thisUpdate>. +I<*thisUpdate> is assigned only if the I<thisUpdate> argument is not NULL. +Depending on the choice present, either I<*dpn> or I<*issuer> will be NULL. +I<*thisUpdate> can also be NULL if the field is not present. + +OSSL_CMP_ITAV_new0_crlStatusList() creates a new B<OSSL_CMP_ITAV> structure of +type B<crlStatusList> that includes the optionally given list of +CRL status data, each of which is of type B<OSSL_CMP_CRLSTATUS>. + +OSSL_CMP_ITAV_get0_crlStatusList() on success assigns to I<*out> an internal +pointer to the list of CRL status data in the infoValue field of I<itav>. +The pointer may be NULL if no CRL status data is included. +It is an error if the infoType of I<itav> is not B<crlStatusList>. + +OSSL_CMP_ITAV_new_crls() creates a new B<OSSL_CMP_ITAV> structure +of type B<crls> including an empty list of CRLs if the I<crl> argument is NULL +or including a singleton list a with copy of the provided CRL otherwise. + +OSSL_CMP_ITAV_get0_crls() on success assigns to I<*out> an internal pointer to +the list of CRLs contained in the infoValue field of I<itav>. +The pointer may be NULL if no CRL is included. +It is an error if the infoType of I<itav> is not B<crls>. =head1 NOTES @@ -67,12 +148,15 @@ CMP is defined in RFC 4210. =head1 RETURN VALUES -OSSL_CMP_ITAV_new_caCerts(), -OSSL_CMP_ITAV_new_rootCaCert(), and OSSL_CMP_ITAV_new_rootCaKeyUpdate() +OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_new_rootCaCert(), +OSSL_CMP_ITAV_new_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_new1(), +OSSL_CMP_CRLSTATUS_create(), OSSL_CMP_ITAV_new0_crlStatusList() +and OSSL_CMP_ITAV_new_crls() return a pointer to the new ITAV structure on success, or NULL on error. -OSSL_CMP_ITAV_get0_caCerts(), -OSSL_CMP_ITAV_get0_rootCaCert(), and OSSL_CMP_ITAV_get0_rootCaKeyUpdate() +OSSL_CMP_ITAV_get0_caCerts(), OSSL_CMP_ITAV_get0_rootCaCert(), +OSSL_CMP_ITAV_get0_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_get0(), +OSSL_CMP_ITAV_get0_crlStatusList() and OSSL_CMP_ITAV_get0_crls() return 1 on success, 0 on error. =head1 SEE ALSO @@ -86,6 +170,11 @@ OSSL_CMP_ITAV_new_rootCaCert(), OSSL_CMP_ITAV_get0_rootCaCert(), OSSL_CMP_ITAV_new_rootCaKeyUpdate(), and OSSL_CMP_ITAV_get0_rootCaKeyUpdate() were added in OpenSSL 3.2. +OSSL_CMP_CRLSTATUS_new1(), OSSL_CMP_CRLSTATUS_create(), +OSSL_CMP_CRLSTATUS_get0(), OSSL_CMP_ITAV_new0_crlStatusList(), +OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_new_crls() +and OSSL_CMP_ITAV_get0_crls() were added in OpenSSL 3.4. + =head1 COPYRIGHT Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. |