1.\" $OpenBSD: CMS_get0_SignerInfos.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $ 2.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2008, 2013 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: November 2 2019 $ 52.Dt CMS_GET0_SIGNERINFOS 3 53.Os 54.Sh NAME 55.Nm CMS_get0_SignerInfos , 56.Nm CMS_SignerInfo_get0_signer_id , 57.Nm CMS_SignerInfo_get0_signature , 58.Nm CMS_SignerInfo_cert_cmp , 59.Nm CMS_SignerInfo_set1_signer_cert 60.Nd CMS SignedData signer functions 61.Sh SYNOPSIS 62.In openssl/cms.h 63.Ft STACK_OF(CMS_SignerInfo) * 64.Fo CMS_get0_SignerInfos 65.Fa "CMS_ContentInfo *cms" 66.Fc 67.Ft int 68.Fo CMS_SignerInfo_get0_signer_id 69.Fa "CMS_SignerInfo *si" 70.Fa "ASN1_OCTET_STRING **keyid" 71.Fa "X509_NAME **issuer" 72.Fa "ASN1_INTEGER **sno" 73.Fc 74.Ft ASN1_OCTET_STRING * 75.Fo CMS_SignerInfo_get0_signature 76.Fa "CMS_SignerInfo *si" 77.Fc 78.Ft int 79.Fo CMS_SignerInfo_cert_cmp 80.Fa "CMS_SignerInfo *si" 81.Fa "X509 *certificate" 82.Fc 83.Ft void 84.Fo CMS_SignerInfo_set1_signer_cert 85.Fa "CMS_SignerInfo *si" 86.Fa "X509 *signer" 87.Fc 88.Sh DESCRIPTION 89.Fn CMS_get0_SignerInfos 90returns all the 91.Vt SignerInfo 92structures associated with the 93.Vt SignedData 94structure 95.Fa cms . 96.Pp 97.Fn CMS_SignerInfo_get0_signer_id 98retrieves the certificate 99.Vt SignerIdentifier 100associated with the 101.Vt SignerInfo 102structure 103.Fa si . 104Either the 105.Vt SubjectKeyIdentifier 106will be set in 107.Fa keyid 108or both issuer name and serial number in 109.Fa issuer 110and 111.Fa sno . 112.Pp 113.Fn CMS_SignerInfo_get0_signature 114retrieves the 115.Fa signature 116field of 117.Fa si . 118The application program is allowed to modify the data pointed to. 119.Pp 120.Fn CMS_SignerInfo_cert_cmp 121compares the 122.Fa certificate 123against the signer identifier of 124.Fa si . 125.Pp 126.Fn CMS_SignerInfo_set1_signer_cert 127sets the signer certificate of 128.Fa si 129to 130.Fa signer . 131.Pp 132The main purpose of these functions is to enable an application to 133look up signer certificates using any appropriate technique when the 134simpler method of 135.Xr CMS_verify 3 136is not appropriate. 137.Pp 138In typical usage, an application retrieves all 139.Vt CMS_SignerInfo 140structures using 141.Fn CMS_get0_SignerInfos 142and retrieves the identifier information using CMS. 143It will then obtain the signer certificate by some unspecified means 144(or return and error if it cannot be found) and set it using 145.Fn CMS_SignerInfo_set1_signer_cert . 146Once all signer certificates have been set, 147.Xr CMS_verify 3 148can be used. 149.Sh RETURN VALUES 150.Fn CMS_get0_SignerInfos 151returns an internal pointer to all the 152.Vt CMS_SignerInfo 153structures, or 154.Dv NULL 155if there are no signers or if 156.Fa cms 157is not of the type 158.Vt SignedData . 159.Pp 160.Fn CMS_SignerInfo_get0_signer_id 161returns 1 for success or 0 for failure. 162.Pp 163.Fn CMS_SignerInfo_get0_signature 164returns an internal pointer to the signature. 165.Pp 166.Fn CMS_SignerInfo_cert_cmp 167returns 0 for a match or non-zero otherwise. 168.Pp 169Any error can be obtained from 170.Xr ERR_get_error 3 . 171.Sh SEE ALSO 172.Xr CMS_ContentInfo_new 3 , 173.Xr CMS_verify 3 174.Sh STANDARDS 175RFC 5652: Cryptographic Message Syntax (CMS) 176.Bl -dash -compact -offset indent 177.It 178section 5.1: SignedData Type 179.It 180section 5.3: SignerInfo Type 181.El 182.Sh HISTORY 183.Fn CMS_get0_SignerInfos , 184.Fn CMS_SignerInfo_get0_signer_id , 185.Fn CMS_SignerInfo_cert_cmp , 186and 187.Fn CMS_SignerInfo_set1_signer_cert 188first appeared in OpenSSL 0.9.8h and 189.Fn CMS_SignerInfo_get0_signature 190in OpenSSL 1.0.2. 191These functions have been available since 192.Ox 6.7 . 193