1.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.13 2020/06/10 11:43:08 schwarze Exp $ 2.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2007, 2008, 2009, 2015 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 10 2020 $ 53.Dt PKCS7_SIGN_ADD_SIGNER 3 54.Os 55.Sh NAME 56.Nm PKCS7_sign_add_signer 57.Nd add a signer to a SignedData structure 58.Sh SYNOPSIS 59.In openssl/pkcs7.h 60.Ft PKCS7_SIGNER_INFO * 61.Fo PKCS7_sign_add_signer 62.Fa "PKCS7 *p7" 63.Fa "X509 *signcert" 64.Fa "EVP_PKEY *pkey" 65.Fa "const EVP_MD *md" 66.Fa "int flags" 67.Fc 68.Sh DESCRIPTION 69.Fn PKCS7_sign_add_signer 70adds a signer with certificate 71.Fa signcert 72and private key 73.Fa pkey 74using message digest 75.Fa md 76to a 77.Vt PKCS7 78signed data structure 79.Fa p7 . 80.Pp 81The 82.Vt PKCS7 83structure should be obtained from an initial call to 84.Xr PKCS7_sign 3 85with the flag 86.Dv PKCS7_PARTIAL 87set or, in the case or re-signing, a valid 88.Vt PKCS7 89signed data structure. 90.Pp 91If the 92.Fa md 93parameter is 94.Dv NULL , 95then the default digest for the public key algorithm will be used. 96.Pp 97Unless the 98.Dv PKCS7_REUSE_DIGEST 99flag is set, the returned 100.Dv PKCS7 101structure is not complete and must be 102finalized either by streaming (if applicable) or by a call to 103.Xr PKCS7_final 3 . 104.Pp 105The main purpose of this function is to provide finer control over a 106PKCS#7 signed data structure where the simpler 107.Xr PKCS7_sign 3 108function defaults are not appropriate, for example if multiple 109signers or non default digest algorithms are needed. 110.Pp 111Any of the following flags (OR'ed together) can be passed in the 112.Fa flags 113parameter. 114.Pp 115If 116.Dv PKCS7_REUSE_DIGEST 117is set, then an attempt is made to copy the content digest value from the 118.Vt PKCS7 119structure: to add a signer to an existing structure. 120An error occurs if a matching digest value cannot be found to copy. 121The returned 122.Vt PKCS7 123structure will be valid and finalized when this flag is set. 124.Pp 125If 126.Dv PKCS7_PARTIAL 127is set in addition to 128.Dv PKCS7_REUSE_DIGEST , 129then the 130.Dv PKCS7_SIGNER_INO 131structure will not be finalized, so additional attributes can be added. 132In this case an explicit call to 133.Fn PKCS7_SIGNER_INFO_sign 134is needed to finalize it. 135.Pp 136If 137.Dv PKCS7_NOCERTS 138is set, the signer's certificate will not be included in the 139.Vt PKCS7 140structure, though the signer's certificate must still be supplied in the 141.Fa signcert 142parameter. 143This can reduce the size of the signature if the signers certificate can 144be obtained by other means: for example a previously signed message. 145.Pp 146The signedData structure includes several PKCS#7 authenticatedAttributes 147including the signing time, the PKCS#7 content type and the supported 148list of ciphers in an SMIMECapabilities attribute. 149If 150.Dv PKCS7_NOATTR 151is set, then no authenticatedAttributes will be used. 152If 153.Dv PKCS7_NOSMIMECAP 154is set, then just the SMIMECapabilities are omitted. 155.Pp 156If present, the SMIMECapabilities attribute indicates support for the 157following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES 158and 40-bit RC2. 159If any of these algorithms is disabled, then it will not be included. 160.Pp 161.Fn PKCS7_sign_add_signer 162returns an internal pointer to the 163.Vt PKCS7_SIGNER_INFO 164structure just added, which can be used to set additional attributes 165with the functions described in 166.Xr PKCS7_add_attribute 3 167before it is finalized. 168.Sh RETURN VALUES 169.Fn PKCS7_sign_add_signer 170returns an internal pointer to the 171.Vt PKCS7_SIGNER_INFO 172structure just added or 173.Dv NULL 174if an error occurs. 175In some cases of failure, the reason can be determined with 176.Xr ERR_get_error 3 . 177.Sh SEE ALSO 178.Xr EVP_DigestInit 3 , 179.Xr PKCS7_add_attribute 3 , 180.Xr PKCS7_final 3 , 181.Xr PKCS7_get_signer_info 3 , 182.Xr PKCS7_new 3 , 183.Xr PKCS7_sign 3 184.Sh HISTORY 185.Fn PKCS7_sign_add_signer 186first appeared in OpenSSL 1.0.0 and has been available since 187.Ox 4.9 . 188