1273138Sjkim=pod 2273138Sjkim 3273138Sjkim=head1 NAME 4273138Sjkim 5273138Sjkim CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. 6273138Sjkim 7273138Sjkim=head1 SYNOPSIS 8273138Sjkim 9273138Sjkim #include <openssl/cms.h> 10273138Sjkim 11273138Sjkim CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); 12273138Sjkim 13273138Sjkim int CMS_SignerInfo_sign(CMS_SignerInfo *si); 14273138Sjkim 15273138Sjkim 16273138Sjkim=head1 DESCRIPTION 17273138Sjkim 18273138SjkimCMS_add1_signer() adds a signer with certificate B<signcert> and private 19273138Sjkimkey B<pkey> using message digest B<md> to CMS_ContentInfo SignedData 20273138Sjkimstructure B<cms>. 21273138Sjkim 22273138SjkimThe CMS_ContentInfo structure should be obtained from an initial call to 23273138SjkimCMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a 24273138Sjkimvalid CMS_ContentInfo SignedData structure. 25273138Sjkim 26273138SjkimIf the B<md> parameter is B<NULL> then the default digest for the public 27273138Sjkimkey algorithm will be used. 28273138Sjkim 29273138SjkimUnless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo 30273138Sjkimstructure is not complete and must be finalized either by streaming (if 31273138Sjkimapplicable) or a call to CMS_final(). 32273138Sjkim 33273138SjkimThe CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo 34273138Sjkimstructure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags 35273138Sjkimare both set. 36273138Sjkim 37273138Sjkim=head1 NOTES 38273138Sjkim 39273138SjkimThe main purpose of CMS_add1_signer() is to provide finer control 40273138Sjkimover a CMS signed data structure where the simpler CMS_sign() function defaults 41273138Sjkimare not appropriate. For example if multiple signers or non default digest 42273138Sjkimalgorithms are needed. New attributes can also be added using the returned 43273138SjkimCMS_SignerInfo structure and the CMS attribute utility functions or the 44273138SjkimCMS signed receipt request functions. 45273138Sjkim 46273138SjkimAny of the following flags (ored together) can be passed in the B<flags> 47273138Sjkimparameter. 48273138Sjkim 49273138SjkimIf B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content 50273138Sjkimdigest value from the CMS_ContentInfo structure: to add a signer to an existing 51273138Sjkimstructure. An error occurs if a matching digest value cannot be found to copy. 52273138SjkimThe returned CMS_ContentInfo structure will be valid and finalized when this 53273138Sjkimflag is set. 54273138Sjkim 55273138SjkimIf B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the 56273138SjkimCMS_SignerInfo structure will not be finalized so additional attributes 57273138Sjkimcan be added. In this case an explicit call to CMS_SignerInfo_sign() is 58273138Sjkimneeded to finalize it. 59273138Sjkim 60273138SjkimIf B<CMS_NOCERTS> is set the signer's certificate will not be included in the 61273138SjkimCMS_ContentInfo structure, the signer's certificate must still be supplied in 62273138Sjkimthe B<signcert> parameter though. This can reduce the size of the signature if 63273138Sjkimthe signers certificate can be obtained by other means: for example a 64273138Sjkimpreviously signed message. 65273138Sjkim 66273138SjkimThe SignedData structure includes several CMS signedAttributes including the 67273138Sjkimsigning time, the CMS content type and the supported list of ciphers in an 68273138SjkimSMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes 69273138Sjkimwill be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are 70273138Sjkimomitted. 71273138Sjkim 72273138SjkimOpenSSL will by default identify signing certificates using issuer name 73273138Sjkimand serial number. If B<CMS_USE_KEYID> is set it will use the subject key 74273138Sjkimidentifier value instead. An error occurs if the signing certificate does not 75273138Sjkimhave a subject key identifier extension. 76273138Sjkim 77273138SjkimIf present the SMIMECapabilities attribute indicates support for the following 78273138Sjkimalgorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 79273138Sjkimbit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. 80273138SjkimIf 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 81273138Sjkimnot loaded. 82273138Sjkim 83273138SjkimCMS_add1_signer() returns an internal pointer to the CMS_SignerInfo 84273138Sjkimstructure just added, this can be used to set additional attributes 85273138Sjkimbefore it is finalized. 86273138Sjkim 87273138Sjkim=head1 RETURN VALUES 88273138Sjkim 89273138SjkimCMS_add1_signer() returns an internal pointer to the CMS_SignerInfo 90273138Sjkimstructure just added or NULL if an error occurs. 91273138Sjkim 92273138Sjkim=head1 SEE ALSO 93273138Sjkim 94273138SjkimL<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, 95273138SjkimL<CMS_final(3)|CMS_final(3)>, 96273138Sjkim 97273138Sjkim=head1 HISTORY 98273138Sjkim 99273138SjkimCMS_add1_signer() was added to OpenSSL 0.9.8 100273138Sjkim 101273138Sjkim=cut 102