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