CMS_add1_signer.pod revision 273149
1238384Sjkim=pod
2238384Sjkim
3238384Sjkim=head1 NAME
4238384Sjkim
5238384Sjkim CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
6238384Sjkim
7238384Sjkim=head1 SYNOPSIS
8238384Sjkim
9238384Sjkim #include <openssl/cms.h>
10238384Sjkim
11238384Sjkim CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
12238384Sjkim
13238384Sjkim int CMS_SignerInfo_sign(CMS_SignerInfo *si);
14238384Sjkim
15238384Sjkim
16238384Sjkim=head1 DESCRIPTION
17238384Sjkim
18238384SjkimCMS_add1_signer() adds a signer with certificate B<signcert> and private
19238384Sjkimkey B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
20238384Sjkimstructure B<cms>.
21238384Sjkim
22238384SjkimThe CMS_ContentInfo structure should be obtained from an initial call to
23238384SjkimCMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
24238384Sjkimvalid CMS_ContentInfo SignedData structure.
25238384Sjkim
26238384SjkimIf the B<md> parameter is B<NULL> then the default digest for the public
27238384Sjkimkey algorithm will be used.
28238384Sjkim
29238384SjkimUnless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
30238384Sjkimstructure is not complete and must be finalized either by streaming (if
31238384Sjkimapplicable) or a call to CMS_final().
32238384Sjkim
33238384SjkimThe CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
34238384Sjkimstructure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
35238384Sjkimare both set.
36238384Sjkim
37238384Sjkim=head1 NOTES
38238384Sjkim
39238384SjkimThe main purpose of CMS_add1_signer() is to provide finer control
40238384Sjkimover a CMS signed data structure where the simpler CMS_sign() function defaults
41238384Sjkimare not appropriate. For example if multiple signers or non default digest
42238384Sjkimalgorithms are needed. New attributes can also be added using the returned
43238384SjkimCMS_SignerInfo structure and the CMS attribute utility functions or the
44238384SjkimCMS signed receipt request functions.
45238384Sjkim
46238384SjkimAny of the following flags (ored together) can be passed in the B<flags>
47238384Sjkimparameter.
48238384Sjkim
49238384SjkimIf B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
50238384Sjkimdigest value from the CMS_ContentInfo structure: to add a signer to an existing
51238384Sjkimstructure.  An error occurs if a matching digest value cannot be found to copy.
52238384SjkimThe returned CMS_ContentInfo structure will be valid and finalized when this
53238384Sjkimflag is set.
54238384Sjkim
55238384SjkimIf B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the 
56238384SjkimCMS_SignerInfo structure will not be finalized so additional attributes
57238384Sjkimcan be added. In this case an explicit call to CMS_SignerInfo_sign() is
58238384Sjkimneeded to finalize it.
59238384Sjkim
60238384SjkimIf B<CMS_NOCERTS> is set the signer's certificate will not be included in the
61238384SjkimCMS_ContentInfo structure, the signer's certificate must still be supplied in
62238384Sjkimthe B<signcert> parameter though. This can reduce the size of the signature if
63238384Sjkimthe signers certificate can be obtained by other means: for example a
64238384Sjkimpreviously signed message.
65238384Sjkim
66238384SjkimThe SignedData structure includes several CMS signedAttributes including the
67238384Sjkimsigning time, the CMS content type and the supported list of ciphers in an
68238384SjkimSMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
69238384Sjkimwill be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
70238384Sjkimomitted.
71238384Sjkim
72238384SjkimOpenSSL will by default identify signing certificates using issuer name
73238384Sjkimand serial number. If B<CMS_USE_KEYID> is set it will use the subject key
74238384Sjkimidentifier value instead. An error occurs if the signing certificate does not
75238384Sjkimhave a subject key identifier extension.
76238384Sjkim
77238384SjkimIf present the SMIMECapabilities attribute indicates support for the following
78238384Sjkimalgorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
79238384Sjkimbit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
80238384SjkimIf 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
81238384Sjkimnot loaded.
82238384Sjkim
83238384SjkimCMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
84238384Sjkimstructure just added, this can be used to set additional attributes 
85238384Sjkimbefore it is finalized.
86238384Sjkim
87238384Sjkim=head1 RETURN VALUES
88238384Sjkim
89238384SjkimCMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
90238384Sjkimstructure just added or NULL if an error occurs.
91238384Sjkim
92238384Sjkim=head1 SEE ALSO
93238384Sjkim
94238384SjkimL<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
95238384SjkimL<CMS_final(3)|CMS_final(3)>,
96238384Sjkim
97238384Sjkim=head1 HISTORY
98238384Sjkim
99238384SjkimCMS_add1_signer() was added to OpenSSL 0.9.8
100238384Sjkim
101238384Sjkim=cut
102238384Sjkim