1.\" $OpenBSD: CMS_add1_signer.3,v 1.10 2024/04/18 16:50:22 tb Exp $ 2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2008 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: April 18 2024 $ 69.Dt CMS_ADD1_SIGNER 3 70.Os 71.Sh NAME 72.Nm CMS_add1_signer , 73.Nm CMS_SignerInfo_sign 74.Nd add a signer to a CMS SignedData structure 75.Sh SYNOPSIS 76.In openssl/cms.h 77.Ft CMS_SignerInfo * 78.Fo CMS_add1_signer 79.Fa "CMS_ContentInfo *cms" 80.Fa "X509 *signcert" 81.Fa "EVP_PKEY *pkey" 82.Fa "const EVP_MD *md" 83.Fa "unsigned int flags" 84.Fc 85.Ft int 86.Fo CMS_SignerInfo_sign 87.Fa "CMS_SignerInfo *si" 88.Fc 89.Sh DESCRIPTION 90.Fn CMS_add1_signer 91adds a signer with certificate 92.Fa signcert 93and private key 94.Fa pkey 95using message digest 96.Fa md 97to the 98.Fa signerInfos 99field of the 100.Vt SignedData 101structure 102.Fa cms , 103which should have been obtained from an initial call to 104.Xr CMS_sign 3 105with the flag 106.Dv CMS_PARTIAL 107set, or which can be a valid 108.Vt SignedData 109structure in the case of re-signing. 110.Pp 111If 112.Fa md 113is 114.Dv NULL , 115the default digest for the public key algorithm of 116.Fa pkey 117is used. 118.Pp 119Unless the 120.Dv CMS_REUSE_DIGEST 121flag is set, the 122.Fa cms 123structure remains incomplete and must be finalized either by streaming 124(if applicable) or by a call to 125.Xr CMS_final 3 . 126.Pp 127The main purpose of 128.Fn CMS_add1_signer 129is to provide finer control over a CMS 130.Vt SignedData 131structure where the simpler 132.Xr CMS_sign 3 133function defaults are not appropriate, for example if multiple signers 134or non default digest algorithms are needed. 135New attributes can also be added using the returned 136.Vt CMS_SignerInfo 137structure and the CMS attribute utility functions or the CMS signed 138receipt request functions. 139.Pp 140Any of the following flags (OR'ed together) can be passed in the 141.Fa flags 142parameter: 143.Bl -tag -width Ds 144.It Dv CMS_REUSE_DIGEST 145Attempt to copy the content digest value from one of the existing 146.Vt CMS_SignerInfo 147structures in 148.Fa cms 149while adding another signer. 150An error occurs if a matching digest value cannot be found to copy. 151The 152.Fa cms 153structure will be valid and finalized when this flag is set. 154.It Dv CMS_PARTIAL 155If this flag is set in addition to 156.Dv CMS_REUSE_DIGEST , 157the returned 158.Vt CMS_SignerInfo 159structure will not be finalized so additional attributes can be added. 160In this case an explicit call to 161.Fn CMS_SignerInfo_sign 162is needed to finalize it. 163.It Dv CMS_NOCERTS 164Do not add the signer's certificate to the 165.Fa certificates 166field of 167.Fa cms . 168The signer's certificate must still be supplied in the 169.Fa signcert 170parameter though. 171This flag can reduce the size of the signature if the signer's certificate can 172be obtained by other means, for example from a previously signed message. 173.It Dv CMS_NOATTR 174Leave the 175.Fa signedAttrs 176field of the returned 177.Vt CMS_SignedData 178structure empty. 179By default, several CMS 180.Vt SignedAttributes 181are added, including the signing time, the CMS content type, 182and the supported list of ciphers in an 183.Vt SMIMECapabilities 184attribute. 185.It Dv CMS_NOSMIMECAP 186Omit just the 187.Vt SMIMECapabilities 188attribute. 189.It Dv CMS_USE_KEYID 190Use the subject key identifier value to identify signing certificates. 191An error occurs if the signing certificate does not have a subject key 192identifier extension. 193By default, issuer name and serial number are used instead. 194.El 195.Pp 196If present, the 197.Vt SMIMECapabilities 198attribute indicates support for the 199following algorithms in preference order: 256-bit AES, 200192-bit AES, 128-bit AES, triple DES, 128-bit RC2, 64-bit 201RC2, DES and 40-bit RC2. 202If any of these algorithms is not available then it will not be 203included. 204.Pp 205The 206.Fn CMS_SignerInfo_sign 207function explicitly signs 208.Fa si . 209Its main use is when the 210.Dv CMS_REUSE_DIGEST 211and 212.Dv CMS_PARTIAL 213flags were both set in the call to 214.Fn CMS_add1_signer 215that created 216.Fa si . 217.Sh RETURN VALUES 218.Fn CMS_add1_signer 219returns an internal pointer to the new 220.Vt CMS_SignerInfo 221structure just added or 222.Dv NULL 223if an error occurs. 224.Sh SEE ALSO 225.Xr CMS_ContentInfo_new 3 , 226.Xr CMS_final 3 , 227.Xr CMS_sign 3 , 228.Xr ERR_get_error 3 229.Sh STANDARDS 230RFC 5652: Cryptographic Message Syntax, section 5.1: SignedData Type 231.Pp 232RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures 233in the Cryptographic Message Syntax (CMS) 234.Pp 235RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) 236Version\ 4.0 Message Specification 237.Bl -dash -compact -offset indent 238.It 239section 2.5: Attributes and the SignerInfo Type 240.It 241section 2.5.2: SMIMECapabilities Attribute 242.El 243.Sh HISTORY 244.Fn CMS_add1_signer 245and 246.Fn CMS_SignerInfo_sign 247first appeared in OpenSSL 0.9.8h 248and have been available since 249.Ox 6.7 . 250