1.\" $OpenBSD: CMS_get0_SignerInfos.3,v 1.9 2024/01/22 14:00:13 tb 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: January 22 2024 $ 52.Dt CMS_GET0_SIGNERINFOS 3 53.Os 54.Sh NAME 55.Nm CMS_get0_SignerInfos , 56.Nm CMS_SignerInfo_get_version , 57.Nm CMS_SignerInfo_get0_signer_id , 58.Nm CMS_SignerInfo_get0_signature , 59.Nm CMS_SignerInfo_cert_cmp , 60.Nm CMS_SignerInfo_set1_signer_cert 61.Nd CMS SignedData signer functions 62.Sh SYNOPSIS 63.In openssl/cms.h 64.Ft STACK_OF(CMS_SignerInfo) * 65.Fo CMS_get0_SignerInfos 66.Fa "CMS_ContentInfo *cms" 67.Fc 68.Ft int 69.Fo CMS_SignerInfo_get_version 70.Fa "CMS_SignerInfo *si" 71.Fa "long *version" 72.Fc 73.Ft int 74.Fo CMS_SignerInfo_get0_signer_id 75.Fa "CMS_SignerInfo *si" 76.Fa "ASN1_OCTET_STRING **keyid" 77.Fa "X509_NAME **issuer" 78.Fa "ASN1_INTEGER **sno" 79.Fc 80.Ft ASN1_OCTET_STRING * 81.Fo CMS_SignerInfo_get0_signature 82.Fa "CMS_SignerInfo *si" 83.Fc 84.Ft int 85.Fo CMS_SignerInfo_cert_cmp 86.Fa "CMS_SignerInfo *si" 87.Fa "X509 *certificate" 88.Fc 89.Ft void 90.Fo CMS_SignerInfo_set1_signer_cert 91.Fa "CMS_SignerInfo *si" 92.Fa "X509 *signer" 93.Fc 94.Sh DESCRIPTION 95.Fn CMS_get0_SignerInfos 96returns all the 97.Vt SignerInfo 98structures associated with the 99.Vt SignedData 100structure 101.Fa cms . 102.Pp 103.Fn CMS_SignerInfo_get_version 104sets 105.Pf * Fa version 106to the syntax version number of the 107.Vt SignerInfo 108structure 109.Fa si . 110.Pp 111.Fn CMS_SignerInfo_get0_signer_id 112retrieves the certificate 113.Vt SignerIdentifier 114associated with the 115.Vt SignerInfo 116structure 117.Fa si . 118Either the 119.Vt SubjectKeyIdentifier 120will be set in 121.Fa keyid 122or both issuer name and serial number in 123.Fa issuer 124and 125.Fa sno . 126.Pp 127.Fn CMS_SignerInfo_get0_signature 128retrieves the 129.Fa signature 130field of 131.Fa si . 132The application program is allowed to modify the data pointed to. 133.Pp 134.Fn CMS_SignerInfo_cert_cmp 135compares the 136.Fa certificate 137against the signer identifier of 138.Fa si . 139.Pp 140.Fn CMS_SignerInfo_set1_signer_cert 141sets the signer certificate of 142.Fa si 143to 144.Fa signer . 145.Pp 146The main purpose of these functions is to enable an application to 147look up signer certificates using any appropriate technique when the 148simpler method of 149.Xr CMS_verify 3 150is not appropriate. 151.Pp 152In typical usage, an application retrieves all 153.Vt CMS_SignerInfo 154structures using 155.Fn CMS_get0_SignerInfos 156and retrieves the identifier information using CMS. 157It will then obtain the signer certificate by some unspecified means 158(or return and error if it cannot be found) and set it using 159.Fn CMS_SignerInfo_set1_signer_cert . 160Once all signer certificates have been set, 161.Xr CMS_verify 3 162can be used. 163.Sh RETURN VALUES 164.Fn CMS_get0_SignerInfos 165returns an internal pointer to all the 166.Vt CMS_SignerInfo 167structures, or 168.Dv NULL 169if there are no signers or if 170.Fa cms 171is not of the type 172.Vt SignedData . 173.Pp 174.Fn CMS_SignerInfo_get_version 175always succeeds and returns 1. 176.Pp 177.Fn CMS_SignerInfo_get0_signer_id 178returns 1 for success or 0 for failure. 179.Pp 180.Fn CMS_SignerInfo_get0_signature 181returns an internal pointer to the signature. 182.Pp 183.Fn CMS_SignerInfo_cert_cmp 184returns 0 for a match or non-zero otherwise. 185.Pp 186Any error can be obtained from 187.Xr ERR_get_error 3 . 188.Sh SEE ALSO 189.Xr CMS_ContentInfo_new 3 , 190.Xr CMS_signed_add1_attr 3 , 191.Xr CMS_verify 3 192.Sh STANDARDS 193RFC 5652: Cryptographic Message Syntax (CMS) 194.Bl -dash -compact -offset indent 195.It 196section 5.1: SignedData Type 197.It 198section 5.3: SignerInfo Type 199.El 200.Sh HISTORY 201.Fn CMS_get0_SignerInfos , 202.Fn CMS_SignerInfo_get0_signer_id , 203.Fn CMS_SignerInfo_cert_cmp , 204and 205.Fn CMS_SignerInfo_set1_signer_cert 206first appeared in OpenSSL 0.9.8h and 207.Fn CMS_SignerInfo_get0_signature 208in OpenSSL 1.0.2. 209These functions have been available since 210.Ox 6.7 . 211.Pp 212.Fn CMS_SignerInfo_get_version 213first appeared in 214.Ox 7.4 . 215