diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-12-03 18:17:50 +0100 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2023-06-01 09:39:12 +0200 |
commit | d477484d33b7b3572150e21562cf4209c8dd9ef5 (patch) | |
tree | 7f543025da8b4daa1815fcc33cb591b2e6442f93 /doc | |
parent | 985429f4f4423de71cae270330586da990e6797f (diff) |
CMP: add support for genm/genp messages with id-it-caCerts
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/19231)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build.info | 6 | ||||
-rw-r--r-- | doc/internal/man3/ossl_cmp_mock_srv_new.pod | 7 | ||||
-rw-r--r-- | doc/man1/openssl-cmp.pod.in | 4 | ||||
-rw-r--r-- | doc/man3/OSSL_CMP_ITAV_new_caCerts.pod | 59 | ||||
-rw-r--r-- | doc/man3/OSSL_CMP_exec_certreq.pod | 15 |
5 files changed, 85 insertions, 6 deletions
diff --git a/doc/build.info b/doc/build.info index 52db908985..6031a85d4d 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1591,6 +1591,10 @@ DEPEND[html/man3/OSSL_CMP_HDR_get0_transactionID.html]=man3/OSSL_CMP_HDR_get0_tr GENERATE[html/man3/OSSL_CMP_HDR_get0_transactionID.html]=man3/OSSL_CMP_HDR_get0_transactionID.pod DEPEND[man/man3/OSSL_CMP_HDR_get0_transactionID.3]=man3/OSSL_CMP_HDR_get0_transactionID.pod GENERATE[man/man3/OSSL_CMP_HDR_get0_transactionID.3]=man3/OSSL_CMP_HDR_get0_transactionID.pod +DEPEND[html/man3/OSSL_CMP_ITAV_new_caCerts.html]=man3/OSSL_CMP_ITAV_new_caCerts.pod +GENERATE[html/man3/OSSL_CMP_ITAV_new_caCerts.html]=man3/OSSL_CMP_ITAV_new_caCerts.pod +DEPEND[man/man3/OSSL_CMP_ITAV_new_caCerts.3]=man3/OSSL_CMP_ITAV_new_caCerts.pod +GENERATE[man/man3/OSSL_CMP_ITAV_new_caCerts.3]=man3/OSSL_CMP_ITAV_new_caCerts.pod DEPEND[html/man3/OSSL_CMP_ITAV_set0.html]=man3/OSSL_CMP_ITAV_set0.pod GENERATE[html/man3/OSSL_CMP_ITAV_set0.html]=man3/OSSL_CMP_ITAV_set0.pod DEPEND[man/man3/OSSL_CMP_ITAV_set0.3]=man3/OSSL_CMP_ITAV_set0.pod @@ -3289,6 +3293,7 @@ html/man3/OSSL_ALGORITHM.html \ html/man3/OSSL_CALLBACK.html \ html/man3/OSSL_CMP_CTX_new.html \ html/man3/OSSL_CMP_HDR_get0_transactionID.html \ +html/man3/OSSL_CMP_ITAV_new_caCerts.html \ html/man3/OSSL_CMP_ITAV_set0.html \ html/man3/OSSL_CMP_MSG_get0_header.html \ html/man3/OSSL_CMP_MSG_http_perform.html \ @@ -3924,6 +3929,7 @@ man/man3/OSSL_ALGORITHM.3 \ man/man3/OSSL_CALLBACK.3 \ man/man3/OSSL_CMP_CTX_new.3 \ man/man3/OSSL_CMP_HDR_get0_transactionID.3 \ +man/man3/OSSL_CMP_ITAV_new_caCerts.3 \ man/man3/OSSL_CMP_ITAV_set0.3 \ man/man3/OSSL_CMP_MSG_get0_header.3 \ man/man3/OSSL_CMP_MSG_http_perform.3 \ diff --git a/doc/internal/man3/ossl_cmp_mock_srv_new.pod b/doc/internal/man3/ossl_cmp_mock_srv_new.pod index 119077ea7c..59568c65fc 100644 --- a/doc/internal/man3/ossl_cmp_mock_srv_new.pod +++ b/doc/internal/man3/ossl_cmp_mock_srv_new.pod @@ -45,16 +45,17 @@ ossl_cmp_mock_srv_set1_refCert() sets the reference certificate to be expected for rr messages and for any oldCertID included in kur messages. ossl_cmp_mock_srv_set1_certOut() sets the certificate to be returned in -cp/ip/kup. +cp/ip/kup messages. Note that on each certificate request the mock server does not produce a fresh certificate but just returns the same pre-existing certificate. ossl_cmp_mock_srv_set1_chainOut() sets the certificate chain to be added to -the extraCerts in a cp/ip/kup. +the extraCerts in a cp/ip/kup message. It should be useful for the validation of the certificate given via ossl_cmp_mock_srv_set1_certOut(). -ossl_cmp_mock_srv_set1_caPubsOut() sets the caPubs to be returned in an ip. +ossl_cmp_mock_srv_set1_caPubsOut() sets the caPubs to be returned in an ip msg +and the list of certificates to be returned in a genp of infoType caCerts. ossl_cmp_mock_srv_set_statusInfo() sets the status info to be returned. diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 76c4313bd5..2c8a8b2540 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -236,6 +236,7 @@ ITAV B<infoType>s is printed to stdout. Set InfoType name to use for requesting specific info in B<genm>, e.g., C<signKeyPairTypes>. +So far, there is specific support for C<caCerts>. =item B<-geninfo> I<OID:int:N> @@ -655,7 +656,8 @@ field of the last received response message that is not a pollRep nor PKIConf. =item B<-cacertsout> I<filename> The file where to save the list of CA certificates contained in the caPubs field -if a positive certificate response (i.e., IP, CP, or KUP) message was received. +if a positive certificate response (i.e., IP, CP, or KUP) message was received +or contained in a general response (genp) message with infoType C<caCerts>. =back diff --git a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod new file mode 100644 index 0000000000..eb397388aa --- /dev/null +++ b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +OSSL_CMP_ITAV_new_caCerts, +OSSL_CMP_ITAV_get0_caCerts +- 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); + +=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. + +=head1 NOTES + +CMP is defined in RFC 4210. + +=head1 RETURN VALUES + +OSSL_CMP_ITAV_new_caCerts() +returns a pointer to the new ITAV structure on success, or NULL on error. + +OSSL_CMP_ITAV_get0_caCerts() +returns 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() and +OSSL_CMP_ITAV_get0_rootCaCert() +were added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2022 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/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod index b0d81c7c41..a418657e3c 100644 --- a/doc/man3/OSSL_CMP_exec_certreq.pod +++ b/doc/man3/OSSL_CMP_exec_certreq.pod @@ -13,7 +13,8 @@ OSSL_CMP_P10CR, OSSL_CMP_KUR, OSSL_CMP_try_certreq, OSSL_CMP_exec_RR_ses, -OSSL_CMP_exec_GENM_ses +OSSL_CMP_exec_GENM_ses, +OSSL_CMP_get_caCerts - functions implementing CMP client transactions =head1 SYNOPSIS @@ -34,6 +35,7 @@ OSSL_CMP_exec_GENM_ses const OSSL_CRMF_MSG *crm, int *checkAfter); int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx); STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx); + int OSSL_CMP_get_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out); =head1 DESCRIPTION @@ -115,6 +117,12 @@ and returns the list of B<ITAV>s received in the GENP message. This can be used, for instance, to poll for CRLs or CA Key Updates. See RFC 4210 section 5.3.19 and appendix E.5 for details. +OSSL_CMP_get_caCerts() uses a genm/gemp message exchange with infoType caCerts +to obtain a list of CA certificates from the CMP server referenced by I<ctx>. +On success it assigns to I<*out> the list of certificates received, +which must be freed by the caller. +NULL means that no CA certificate is available at the server. + =head1 NOTES CMP is defined in RFC 4210 (and CRMF in RFC 4211). @@ -138,7 +146,8 @@ In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL and the output parameter I<checkAfter> has been used to assign the received value unless I<checkAfter> is NULL. -OSSL_CMP_exec_RR_ses() returns 1 on success, 0 on error. +OSSL_CMP_exec_RR_ses() and OSSL_CMP_get_caCerts() +return 1 on success, 0 on error. OSSL_CMP_exec_GENM_ses() returns NULL on error, otherwise a pointer to the sequence of B<ITAV> received, which may be empty. @@ -161,6 +170,8 @@ L<OSSL_CMP_MSG_http_perform(3)> The OpenSSL CMP support was added in OpenSSL 3.0. +OSSL_CMP_get_caCerts() was added in OpenSSL 3.2. + =head1 COPYRIGHT Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved. |