1.Dd $Mdocdate: November 11 2015 $ 2.Dt CMS_SIGN 3 3.Os 4.Sh NAME 5.Nm CMS_sign 6.Nd create a CMS SignedData structure 7.Sh SYNOPSIS 8.In openssl/cms.h 9.Ft CMS_ContentInfo * 10.Fo CMS_sign 11.Fa "X509 *signcert" 12.Fa "EVP_PKEY *pkey" 13.Fa "STACK_OF(X509) *certs" 14.Fa "BIO *data" 15.Fa "unsigned int flags" 16.Fc 17.Sh DESCRIPTION 18.Fn CMS_sign 19creates and returns a CMS SignedData structure. 20.Fa signcert 21is the certificate to sign with, 22.Fa pkey 23is the corresponding private key. 24.Fa certs 25is an optional additional set of certificates to include in the CMS 26structure (for example any intermediate CAs in the chain). 27Any or all of these parameters can be 28.Dv NULL , 29see 30.Sx NOTES 31below. 32.Pp 33The data to be signed is read from 34.Fa data . 35.Pp 36.Fa flags 37is an optional set of flags. 38.Sh NOTES 39Any of the following flags (OR'ed together) can be passed in the 40.Fa flags 41parameter. 42.Pp 43Many S/MIME clients expect the signed content to include valid MIME 44headers. 45If the 46.Dv CMS_TEXT 47flag is set, MIME headers for type 48.Sy text/plain 49are prepended to the data. 50.Pp 51If 52.Dv CMS_NOCERTS 53is set, the signer's certificate will not be included in the 54.Vt CMS_ContentInfo 55structure, the signer's certificate must still be supplied in the 56.Fa signcert 57parameter though. 58This can reduce the size of the signature if the signers certificate can 59be obtained by other means: for example a previously signed message. 60.Pp 61The data being signed is included in the 62.Vt CMS_ContentInfo 63structure, unless 64.Dv CMS_DETACHED 65is set, in which case it is omitted. 66This is used for 67.Vt CMS_ContentInfo 68detached signatures which are used in S/MIME plaintext signed 69messages for example. 70.Pp 71Normally the supplied content is translated into MIME canonical format 72(as required by the S/MIME specifications); if 73.Dv CMS_BINARY 74is set, no translation occurs. 75This option should be used if the supplied data is in binary format; 76otherwise the translation will corrupt it. 77.Pp 78The SignedData structure includes several CMS signedAttributes including 79the signing time, the CMS content type and the supported list of ciphers 80in an SMIMECapabilities attribute. 81If 82.Dv CMS_NOATTR 83is set, then no signedAttributes will be used. 84If 85.Dv CMS_NOSMIMECAP 86is set, then just the SMIMECapabilities are omitted. 87.Pp 88If present, the SMIMECapabilities attribute indicates support for the 89following algorithms in preference order: 256 bit AES, Gost R3411-94, 90Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit 91RC2, DES and 40 bit RC2. 92If any of these algorithms is not available, then it will not be 93included: for example the GOST algorithms will not be included if 94the GOST ENGINE is not loaded. 95.Pp 96OpenSSL will by default identify signing certificates using issuer name 97and serial number. 98If 99.Dv CMS_USE_KEYID 100is set, it will use the subject key identifier value instead. 101An error occurs if the signing certificate does not have a subject key 102identifier extension. 103.Pp 104If the flag 105.Dv CMS_STREAM 106is set, then the returned 107.Vt CMS_ContentInfo 108structure is just initialized ready to perform the signing operation. 109The signing is however 110.Em not 111performed and the data to be signed is not read from the 112.Fa data 113parameter. 114Signing is deferred until after the data has been written. 115In this way, data can be signed in a single pass. 116.Pp 117If the 118.Dv CMS_PARTIAL 119flag is set, a partial 120.Vt CMS_ContentInfo 121structure is output to which additional signers and capabilities can be 122added before finalization. 123.Pp 124If the flag 125.Dv CMS_STREAM 126is set, the returned 127.Vt CMS_ContentInfo 128structure is 129.Em not 130complete and outputting its contents via a function that does not 131properly finalize the 132.Vt CMS_ContentInfo 133structure will give unpredictable results. 134.Pp 135Several functions including 136.Xr SMIME_write_CMS 3 , 137.Xr i2d_CMS_bio_stream 3 , 138.Xr PEM_write_bio_CMS_stream 3 139finalize the structure. 140Alternatively finalization can be performed by obtaining the streaming 141ASN1 142.Vt BIO 143directly using 144.Xr BIO_new_CMS 3 . 145.Pp 146If a signer is specified, it will use the default digest for the signing 147algorithm. 148This is SHA1 for both RSA and DSA keys. 149.Pp 150If 151.Fa signcert 152and 153.Fa pkey 154are 155.Dv NULL , 156then a certificates only CMS structure is output. 157.Pp 158The function 159.Fn CMS_sign 160is a basic CMS signing function whose output will be suitable for many 161purposes. 162For finer control of the output format the 163.Fa certs , 164.Fa signcert 165and 166.Fa pkey 167parameters can all be 168.Dv NULL 169and the 170.Dv CMS_PARTIAL 171flag set. 172Then one or more signers can be added using the function 173.Xr CMS_sign_add1_signer 3 , 174non default digests can be used and custom attributes added. 175.Xr CMS_final 3 176must then be called to finalize the structure if streaming is not 177enabled. 178.Sh RETURN VALUES 179.Fn CMS_sign 180returns either a valid 181.Vt CMS_ContentInfo 182structure or 183.Dv NULL 184if an error occurred. 185The error can be obtained from 186.Xr ERR_get_error 3 . 187.Sh SEE ALSO 188.Xr CMS_verify 3 , 189.Xr ERR_get_error 3 190.Sh HISTORY 191.Fn CMS_sign 192was added to OpenSSL 0.9.8. 193.Pp 194The 195.Dv CMS_STREAM 196flag is only supported for detached data in OpenSSL 0.9.8. 197It is supported for embedded data in OpenSSL 1.0.0 and later. 198.Sh BUGS 199Some attributes such as counter signatures are not supported. 200