mirror of
https://github.com/openssl/openssl.git
synced 2024-11-27 05:21:51 +08:00
219 lines
9.8 KiB
Plaintext
219 lines
9.8 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_CMP_ITAV_new_caCerts,
|
|
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_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,
|
|
OSSL_CMP_ITAV_new0_certReqTemplate,
|
|
OSSL_CMP_ITAV_get1_certReqTemplate
|
|
- CMP utility functions for handling specific genm and genp messages
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/cmp.h>
|
|
|
|
OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_caCerts(const STACK_OF(X509) *caCerts);
|
|
int OSSL_CMP_ITAV_get0_caCerts(const OSSL_CMP_ITAV *itav, STACK_OF(X509) **out);
|
|
|
|
OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaCert(const X509 *rootCaCert);
|
|
int OSSL_CMP_ITAV_get0_rootCaCert(const OSSL_CMP_ITAV *itav, X509 **out);
|
|
OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaKeyUpdate(const X509 *newWithNew,
|
|
const X509 *newWithOld,
|
|
const X509 *oldWithNew);
|
|
int OSSL_CMP_ITAV_get0_rootCaKeyUpdate(const OSSL_CMP_ITAV *itav,
|
|
X509 **newWithNew,
|
|
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);
|
|
OSSL_CMP_ITAV
|
|
*OSSL_CMP_ITAV_new0_certReqTemplate(OSSL_CRMF_CERTTEMPLATE *certTemplate,
|
|
OSSL_CMP_ATAVS *keySpec);
|
|
int OSSL_CMP_ITAV_get1_certReqTemplate(const OSSL_CMP_ITAV *itav,
|
|
OSSL_CRMF_CERTTEMPLATE **certTemplate,
|
|
OSSL_CMP_ATAVS **keySpec);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
ITAV is short for InfoTypeAndValue.
|
|
|
|
OSSL_CMP_ITAV_new_caCerts() creates an B<OSSL_CMP_ITAV> structure of type
|
|
B<caCerts> and fills it with a copy of the provided list of certificates.
|
|
The I<caCerts> argument may be NULL or contain any number of certificates.
|
|
|
|
OSSL_CMP_ITAV_get0_caCerts() requires that I<itav> has type B<caCerts>.
|
|
It assigns NULL to I<*out> if there are no CA certificates in I<itav>, otherwise
|
|
the internal pointer of type B<STACK_OF(X509)> with the certificates present.
|
|
|
|
OSSL_CMP_ITAV_new_rootCaCert() creates a new B<OSSL_CMP_ITAV> structure
|
|
of type B<rootCaCert> that includes the optionally given certificate.
|
|
|
|
OSSL_CMP_ITAV_get0_rootCaCert() requires that I<itav> has type B<rootCaCert>.
|
|
It assigns NULL to I<*out> if no certificate is included in I<itav>, otherwise
|
|
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>.
|
|
If an update of a root CA certificate is included,
|
|
it assigns to I<*newWithNew> the internal pointer
|
|
to the certificate contained in the newWithNew infoValue sub-field of I<itav>.
|
|
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 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:
|
|
|
|
OSSL_CMP_ITAV_new0_certReqTemplate() creates an B<OSSL_CMP_ITAV> structure
|
|
of type B<certReqTemplate>.
|
|
If I<certTemplate> is NULL then also I<keySpec> must be NULL,
|
|
and the resulting ITAV can be used in a B<genm> message to obtain the
|
|
requirements a PKI has on the certificate template used to request certificates,
|
|
or in a B<genp> message stating that there are no such requirements.
|
|
Otherwise the resulting ITAV includes a CertReqTemplateValue structure
|
|
with I<certTemplate> of type B<OSSL_CRMF_CERTTEMPLATE> and an optional list
|
|
of key specifications I<keySpec>, each being of type B<OSSL_CMP_ATAV>, and
|
|
the resulting ATAV can be used in a B<genp> message to provide requirements.
|
|
|
|
OSSL_CMP_ITAV_get1_certReqTemplate()
|
|
requires that I<itav> has type B<certReqTemplate>.
|
|
If assigns NULL to I<*certTemplate> if no B<OSSL_CRMF_CERTTEMPLATE> structure
|
|
with a certificate template value is in I<itav>,
|
|
otherwise a copy of the certTemplate field value.
|
|
If I<keySpec> is not NULL, it is assigned NULL
|
|
if the structure is not present in I<itav> or the keySpec field is absent.
|
|
Otherwise, the function checks that all elements of keySpec field are of type
|
|
B<algId> or B<rsaKeyLen> and assigns to I<*keySpec> a copy of the keySpec field.
|
|
|
|
=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
|
|
|
|
CMP is defined in RFC 4210.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
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(),
|
|
OSSL_CMP_ITAV_new_crls() and OSSL_CMP_ITAV_new0_certReqTemplate()
|
|
return a pointer to the new ITAV structure on success, or NULL on error.
|
|
|
|
OSSL_CMP_ITAV_get0_caCerts(), OSSL_CMP_ITAV_get0_rootCaCert(),
|
|
OSSL_CMP_ITAV_get0_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_get0(),
|
|
OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_get0_crls()
|
|
and OSSL_CMP_ITAV_get1_certReqTemplate()
|
|
return 1 on success, 0 on error.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<OSSL_CMP_ITAV_create(3)> and L<OSSL_CMP_ITAV_get0_type(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_get0_caCerts(),
|
|
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(),
|
|
OSSL_CMP_ITAV_get0_crls(), OSSL_CMP_ITAV_new0_certReqTemplate()
|
|
and OSSL_CMP_ITAV_get1_certReqTemplate() were added in OpenSSL 3.4.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2022-2024 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
|