]>
Commit | Line | Data |
---|---|---|
e33ffaca DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bb9ad09e | 5 | CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure |
e33ffaca DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/cms.h> | |
10 | ||
e9b77246 BB |
11 | CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, |
12 | EVP_PKEY *pkey, const EVP_MD *md, | |
13 | unsigned int flags); | |
e33ffaca | 14 | |
38d3a738 | 15 | int CMS_SignerInfo_sign(CMS_SignerInfo *si); |
e33ffaca | 16 | |
e33ffaca DSH |
17 | =head1 DESCRIPTION |
18 | ||
5886354d | 19 | CMS_add1_signer() adds a signer with certificate B<signcert> and private |
38d3a738 | 20 | key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData |
e33ffaca DSH |
21 | structure B<cms>. |
22 | ||
23 | The CMS_ContentInfo structure should be obtained from an initial call to | |
24 | CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a | |
38d3a738 | 25 | valid CMS_ContentInfo SignedData structure. |
e33ffaca DSH |
26 | |
27 | If the B<md> parameter is B<NULL> then the default digest for the public | |
28 | key algorithm will be used. | |
29 | ||
30 | Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo | |
31 | structure is not complete and must be finalized either by streaming (if | |
32 | applicable) or a call to CMS_final(). | |
33 | ||
34 | The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo | |
35 | structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags | |
36 | are both set. | |
37 | ||
38 | =head1 NOTES | |
39 | ||
5886354d | 40 | The main purpose of CMS_add1_signer() is to provide finer control |
86173db8 DSH |
41 | over a CMS signed data structure where the simpler CMS_sign() function defaults |
42 | are not appropriate. For example if multiple signers or non default digest | |
e33ffaca | 43 | algorithms are needed. New attributes can also be added using the returned |
c420fab5 | 44 | CMS_SignerInfo structure and the CMS attribute utility functions or the |
6469a1fd | 45 | CMS signed receipt request functions. |
e33ffaca DSH |
46 | |
47 | Any of the following flags (ored together) can be passed in the B<flags> | |
48 | parameter. | |
49 | ||
50 | If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content | |
c420fab5 | 51 | digest value from the CMS_ContentInfo structure: to add a signer to an existing |
e33ffaca DSH |
52 | structure. An error occurs if a matching digest value cannot be found to copy. |
53 | The returned CMS_ContentInfo structure will be valid and finalized when this | |
54 | flag is set. | |
55 | ||
1bc74519 | 56 | If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the |
86173db8 DSH |
57 | CMS_SignerInfo structure will not be finalized so additional attributes |
58 | can be added. In this case an explicit call to CMS_SignerInfo_sign() is | |
e33ffaca DSH |
59 | needed to finalize it. |
60 | ||
61 | If B<CMS_NOCERTS> is set the signer's certificate will not be included in the | |
62 | CMS_ContentInfo structure, the signer's certificate must still be supplied in | |
63 | the B<signcert> parameter though. This can reduce the size of the signature if | |
64 | the signers certificate can be obtained by other means: for example a | |
65 | previously signed message. | |
66 | ||
38d3a738 | 67 | The SignedData structure includes several CMS signedAttributes including the |
e33ffaca DSH |
68 | signing time, the CMS content type and the supported list of ciphers in an |
69 | SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes | |
70 | will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are | |
71 | omitted. | |
72 | ||
73 | OpenSSL will by default identify signing certificates using issuer name | |
74 | and serial number. If B<CMS_USE_KEYID> is set it will use the subject key | |
75 | identifier value instead. An error occurs if the signing certificate does not | |
76 | have a subject key identifier extension. | |
77 | ||
78 | If present the SMIMECapabilities attribute indicates support for the following | |
86173db8 DSH |
79 | algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 |
80 | bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. | |
81 | If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is | |
82 | not loaded. | |
e33ffaca | 83 | |
5886354d | 84 | CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo |
1bc74519 | 85 | structure just added, this can be used to set additional attributes |
e33ffaca DSH |
86 | before it is finalized. |
87 | ||
88 | =head1 RETURN VALUES | |
89 | ||
5886354d | 90 | CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo |
e33ffaca DSH |
91 | structure just added or NULL if an error occurs. |
92 | ||
93 | =head1 SEE ALSO | |
94 | ||
9b86974e RS |
95 | L<ERR_get_error(3)>, L<CMS_sign(3)>, |
96 | L<CMS_final(3)>, | |
e33ffaca | 97 | |
e2f92610 RS |
98 | =head1 COPYRIGHT |
99 | ||
100 | Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. | |
101 | ||
102 | Licensed under the OpenSSL license (the "License"). You may not use | |
103 | this file except in compliance with the License. You can obtain a copy | |
104 | in the file LICENSE in the source distribution or at | |
105 | L<https://www.openssl.org/source/license.html>. | |
106 | ||
107 | =cut |