diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2022-06-27 17:05:21 +0200 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2022-07-16 08:15:49 +0200 |
commit | d7d3dae694fa4611c1cd953dccf81b3d2b4121c6 (patch) | |
tree | d4210058c101d76fc666b53c183fbd3e5fa6cff5 /doc/man3/CMS_verify.pod | |
parent | 4329a321c9f939f06e7705fa25ac55af3160acf6 (diff) | |
download | openssl-d7d3dae694fa4611c1cd953dccf81b3d2b4121c6.tar.gz |
CMS: add CMS_SignedData_verify(), a variant of CMS_verify() with extensions
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/18667)
Diffstat (limited to 'doc/man3/CMS_verify.pod')
-rw-r--r-- | doc/man3/CMS_verify.pod | 84 |
1 files changed, 55 insertions, 29 deletions
diff --git a/doc/man3/CMS_verify.pod b/doc/man3/CMS_verify.pod index 6c9595e51e..fa7e44394d 100644 --- a/doc/man3/CMS_verify.pod +++ b/doc/man3/CMS_verify.pod @@ -2,67 +2,86 @@ =head1 NAME -CMS_verify, CMS_get0_signers - verify a CMS SignedData structure +CMS_verify, CMS_SignedData_verify, +CMS_get0_signers - verify a CMS SignedData structure =head1 SYNOPSIS #include <openssl/cms.h> int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, - BIO *indata, BIO *out, unsigned int flags); + BIO *detached_data, BIO *out, unsigned int flags); + BIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data, + STACK_OF(X509) *scerts, X509_STORE *store, + STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls, + unsigned int flags, + OSSL_LIB_CTX *libctx, const char *propq); STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); =head1 DESCRIPTION -CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo -structure to verify. B<certs> is a set of certificates in which to search for -the signing certificate(s). B<store> is a trusted certificate store used for -chain verification. B<indata> is the detached content if the content is not -present in B<cms>. The content is written to B<out> if it is not NULL. - -B<flags> is an optional set of flags, which can be used to modify the verify +CMS_verify() verifies a B<CMS SignedData> structure +contained in a structure of type B<CMS_ContentInfo>. +I<cms> points to the B<CMS_ContentInfo> structure to verify. +I<certs> is a set of certificates in which to search for signing certificate(s). +I<store> is a trusted certificate store used for chain verification. +I<detached_data> refers to the content if the content is not present in I<cms>. +The content is written to the BIO I<out> if it is not NULL. +I<flags> is an optional set of flags, which can be used to modify the verify operation. -CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it may only -be called after a successful CMS_verify() operation. +CMS_SignedData_verify() is like CMS_verify() except that +it operates on B<CMS SignedData> input in the I<sd> argument, +it has some additional parameters described next, +and on success it returns the verfied content as a memory BIO. +The optional I<extra> parameter may be used to provide untrusted CA +certificates that may be helpful for chain building in certificate valiation. +This list of certificates must not contain duplicates. +The optional I<crls> parameter may be used to provide extra CRLs. +Also the list of CRLs must not contain duplicates. +The optional parameters library context I<libctx> and property query I<propq> +are used when retrieving algorithms from providers. + +CMS_get0_signers() retrieves the signing certificate(s) from I<cms>; it may only +be called after a successful CMS_verify() or CMS_SignedData_verify() operation. =head1 VERIFY PROCESS Normally the verify process proceeds as follows. -Initially some sanity checks are performed on B<cms>. The type of B<cms> must +Initially some sanity checks are performed on I<cms>. The type of I<cms> must be SignedData. There must be at least one signature on the data and if -the content is detached B<indata> cannot be B<NULL>. +the content is detached I<detached_data> cannot be NULL. An attempt is made to locate all the signing certificate(s), first looking in -the B<certs> parameter (if it is not NULL) and then looking in any -certificates contained in the B<cms> structure itself. If any signing +the I<certs> parameter (if it is not NULL) and then looking in any +certificates contained in the I<cms> structure itself. If any signing certificate cannot be located the operation fails. -Each signing certificate is chain verified using the B<smimesign> purpose and +Each signing certificate is chain verified using the I<smimesign> purpose and the supplied trusted certificate store. Any internal certificates in the message -are used as untrusted CAs. If CRL checking is enabled in B<store> any internal -CRLs are used in addition to attempting to look them up in B<store>. If any +are used as untrusted CAs. If CRL checking is enabled in I<store> any internal +CRLs are used in addition to attempting to look them up in I<store>. If any chain verify fails an error code is returned. -Finally the signed content is read (and written to B<out> if it is not NULL) +Finally the signed content is read (and written to I<out> if it is not NULL) and the signature's checked. If all signature's verify correctly then the function is successful. -Any of the following flags (ored together) can be passed in the B<flags> +Any of the following flags (ored together) can be passed in the I<flags> parameter to change the default verify behaviour. If B<CMS_NOINTERN> is set the certificates in the message itself are not searched when locating the signing certificate(s). This means that all the -signing certificates must be in the B<certs> parameter. +signing certificates must be in the I<certs> parameter. -If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any -CRLs in the message itself are ignored. +If B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any +CRLs in the message itself and provided via the I<crls> parameter are ignored. -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is +If the B<CMS_TEXT> flag is set MIME headers for type C<text/plain> are deleted +from the content. If the content is not of type C<text/plain> then an error is returned. If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not @@ -81,8 +100,8 @@ If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. One application of B<CMS_NOINTERN> is to only accept messages signed by a small number of certificates. The acceptable certificates would be passed -in the B<certs> parameter. In this case if the signer is not one of the -certificates supplied in B<certs> then the verify will fail because the +in the I<certs> parameter. In this case if the signer is not one of the +certificates supplied in I<certs> then the verify will fail because the signer cannot be found. In some cases the standard techniques for looking up and validating @@ -94,7 +113,7 @@ using the signed data utility functions. Care should be taken when modifying the default verify behaviour, for example setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification and any modified content will be considered valid. This combination is however -useful if one merely wishes to write the content to B<out> and its validity +useful if one merely wishes to write the content to I<out> and its validity is not considered important. Chain verification should arguably be performed using the signing time rather @@ -107,9 +126,12 @@ timestamp). CMS_verify() returns 1 for a successful verification and zero if an error occurred. +CMS_SignedData_verify() returns a memory BIO containing the verfied content, +or NULL on error. + CMS_get0_signers() returns all signers or NULL if an error occurred. -The error can be obtained from L<ERR_get_error(3)> +The error can be obtained from L<ERR_get_error(3)>. =head1 BUGS @@ -125,6 +147,10 @@ be held in memory if it is not detached. L<OSSL_ESS_check_signing_certs(3)>, L<ERR_get_error(3)>, L<CMS_sign(3)> +=head1 HISTORY + +CMS_SignedData_verify() was added in OpenSSL 3.1. + =head1 COPYRIGHT Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved. |