1.Dd $Mdocdate: November 11 2015 $ 2.Dt CMS_SIGN_ADD1_SIGNER 3 3.Os 4.Sh NAME 5.Nm CMS_add1_signer , 6.Nm CMS_SignerInfo_sign 7.Nd add a signer to a CMS_ContentInfo signed data structure 8.Sh SYNOPSIS 9.In openssl/cms.h 10.Ft CMS_SignerInfo * 11.Fo CMS_add1_signer 12.Fa "CMS_ContentInfo *cms" 13.Fa "X509 *signcert" 14.Fa "EVP_PKEY *pkey" 15.Fa "const EVP_MD *md" 16.Fa "unsigned int flags" 17.Fc 18.Ft int 19.Fo CMS_SignerInfo_sign 20.Fa "CMS_SignerInfo *si" 21.Fc 22.Sh DESCRIPTION 23.Fn CMS_add1_signer 24adds a signer with certificate 25.Fa signcert 26and private key 27.Fa pkey 28using message digest 29.Fa md 30to the 31.Vt CMS_ContentInfo 32SignedData structure 33.Fa cms . 34.Pp 35The 36.Vt CMS_ContentInfo 37structure should be obtained from an initial call to 38.Xr CMS_sign 3 39with the flag 40.Dv CMS_PARTIAL 41set or in the case or re-signing a valid 42.Vt CMS_ContentInfo 43SignedData structure. 44.Pp 45If the 46.Fa md 47parameter is 48.Dv NULL , 49then the default digest for the public key algorithm will be used. 50.Pp 51Unless the 52.Dv CMS_REUSE_DIGEST 53flag is set, the returned 54.Vt CMS_ContentInfo 55structure is not complete and must be finalized either by streaming 56(if applicable) or a call to 57.Xr CMS_final 3 . 58.Pp 59The 60.Fn CMS_SignerInfo_sign 61function will explicitly sign a 62.Vt CMS_SignerInfo 63structure, its main use is when 64.Dv CMS_REUSE_DIGEST 65and 66.Dv CMS_PARTIAL 67flags are both set. 68.Sh NOTES 69The main purpose of 70.Fn CMS_add1_signer 71is to provide finer control over a CMS signed data structure where the 72simpler 73.Xr CMS_sign 3 74function defaults are not appropriate. 75For example if multiple signers or non default digest algorithms are 76needed. 77New attributes can also be added using the returned 78.Vt CMS_SignerInfo 79structure and the CMS attribute utility functions or the CMS signed 80receipt request functions. 81.Pp 82Any of the following flags (OR'ed together) can be passed in the 83.Fa flags 84parameter. 85.Pp 86If 87.Dv CMS_REUSE_DIGEST 88is set, then an attempt is made to copy the content digest value from the 89.Dv CMS_ContentInfo 90structure: to add a signer to an existing structure. 91An error occurs if a matching digest value cannot be found to copy. 92The returned 93.Dv CMS_ContentInfo 94structure will be valid and finalized when this flag is set. 95.Pp 96If 97.Dv CMS_PARTIAL 98is set in addition to 99.Dv CMS_REUSE_DIGEST 100then the 101.Vt CMS_SignerInfo 102structure will not be finalized so additional attributes can be added. 103In this case an explicit call to 104.Fn CMS_SignerInfo_sign 105is needed to finalize it. 106.Pp 107If 108.Dv CMS_NOCERTS 109is set, the signer's certificate will not be included in the 110.Vt CMS_ContentInfo 111structure, the signer's certificate must still be supplied in the 112.Fa signcert 113parameter though. 114This can reduce the size of the signature if the signers certificate can 115be obtained by other means: for example a previously signed message. 116.Pp 117The SignedData structure includes several CMS signedAttributes including 118the signing time, the CMS content type and the supported list of ciphers 119in an SMIMECapabilities attribute. 120If 121.Dv CMS_NOATTR 122is set, then no signedAttributes will be used. 123If 124.Dv CMS_NOSMIMECAP 125is set, then just the SMIMECapabilities are omitted. 126.Pp 127OpenSSL will by default identify signing certificates using issuer name 128and serial number. 129If 130.Dv CMS_USE_KEYID 131is set, it will use the subject key identifier value instead. 132An error occurs if the signing certificate does not have a subject key 133identifier extension. 134.Pp 135If present, the SMIMECapabilities attribute indicates support for the 136following algorithms in preference order: 256 bit AES, Gost R3411-94, 137Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit 138RC2, DES and 40 bit RC2. 139If any of these algorithms is not available then it will not be 140included: for example the GOST algorithms will not be included if 141the GOST ENGINE is not loaded. 142.Pp 143.Fn CMS_add1_signer 144returns an internal pointer to the 145.Dv CMS_SignerInfo 146structure just added. 147This can be used to set additional attributes before it is finalized. 148.Sh RETURN VALUES 149.Fn CMS_add1_signer 150returns an internal pointer to the 151.Vt CMS_SignerInfo 152structure just added or 153.Dv NULL 154if an error occurs. 155.Sh SEE ALSO 156.Xr CMS_final 3 , 157.Xr CMS_sign 3 , 158.Xr ERR_get_error 3 159.Sh HISTORY 160.Fn CMS_add1_signer 161was added to OpenSSL 0.9.8. 162