From: Dr. Stephen Henson Date: Sat, 20 Sep 2014 00:00:55 +0000 (+0100) Subject: Use correct function name: CMS_add1_signer() X-Git-Tag: master-post-reformat~362 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=5886354dcca4f8445ed35b6995a035b75409590c;p=oweals%2Fopenssl.git Use correct function name: CMS_add1_signer() Reviewed-by: Matt Caswell --- diff --git a/doc/crypto/CMS_add1_signer.pod b/doc/crypto/CMS_add1_signer.pod new file mode 100644 index 0000000000..a055b82695 --- /dev/null +++ b/doc/crypto/CMS_add1_signer.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + + CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + +=head1 SYNOPSIS + + #include + + CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); + + int CMS_SignerInfo_sign(CMS_SignerInfo *si); + + +=head1 DESCRIPTION + +CMS_add1_signer() adds a signer with certificate B and private +key B using message digest B to CMS_ContentInfo SignedData +structure B. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_sign() with the flag B set or in the case or re-signing a +valid CMS_ContentInfo SignedData structure. + +If the B parameter is B then the default digest for the public +key algorithm will be used. + +Unless the B flag is set the returned CMS_ContentInfo +structure is not complete and must be finalized either by streaming (if +applicable) or a call to CMS_final(). + +The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo +structure, its main use is when B and B flags +are both set. + +=head1 NOTES + +The main purpose of CMS_add1_signer() is to provide finer control +over a CMS signed data structure where the simpler CMS_sign() function defaults +are not appropriate. For example if multiple signers or non default digest +algorithms are needed. New attributes can also be added using the returned +CMS_SignerInfo structure and the CMS attribute utility functions or the +CMS signed receipt request functions. + +Any of the following flags (ored together) can be passed in the B +parameter. + +If B is set then an attempt is made to copy the content +digest value from the CMS_ContentInfo structure: to add a signer to an existing +structure. An error occurs if a matching digest value cannot be found to copy. +The returned CMS_ContentInfo structure will be valid and finalized when this +flag is set. + +If B is set in addition to B then the +CMS_SignerInfo structure will not be finalized so additional attributes +can be added. In this case an explicit call to CMS_SignerInfo_sign() is +needed to finalize it. + +If B is set the signer's certificate will not be included in the +CMS_ContentInfo structure, the signer's certificate must still be supplied in +the B parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. + +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B is set then no signedAttributes +will be used. If B is set then just the SMIMECapabilities are +omitted. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +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 +not loaded. + +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L, L, +L, + +=head1 HISTORY + +CMS_add1_signer() was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/CMS_sign_add1_signer.pod b/doc/crypto/CMS_sign_add1_signer.pod deleted file mode 100644 index bda3ca2adb..0000000000 --- a/doc/crypto/CMS_sign_add1_signer.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - - CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. - -=head1 SYNOPSIS - - #include - - CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); - - int CMS_SignerInfo_sign(CMS_SignerInfo *si); - - -=head1 DESCRIPTION - -CMS_sign_add1_signer() adds a signer with certificate B and private -key B using message digest B to CMS_ContentInfo SignedData -structure B. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_sign() with the flag B set or in the case or re-signing a -valid CMS_ContentInfo SignedData structure. - -If the B parameter is B then the default digest for the public -key algorithm will be used. - -Unless the B flag is set the returned CMS_ContentInfo -structure is not complete and must be finalized either by streaming (if -applicable) or a call to CMS_final(). - -The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo -structure, its main use is when B and B flags -are both set. - -=head1 NOTES - -The main purpose of CMS_sign_add1_signer() is to provide finer control -over a CMS signed data structure where the simpler CMS_sign() function defaults -are not appropriate. For example if multiple signers or non default digest -algorithms are needed. New attributes can also be added using the returned -CMS_SignerInfo structure and the CMS attribute utility functions or the -CMS signed receipt request functions. - -Any of the following flags (ored together) can be passed in the B -parameter. - -If B is set then an attempt is made to copy the content -digest value from the CMS_ContentInfo structure: to add a signer to an existing -structure. An error occurs if a matching digest value cannot be found to copy. -The returned CMS_ContentInfo structure will be valid and finalized when this -flag is set. - -If B is set in addition to B then the -CMS_SignerInfo structure will not be finalized so additional attributes -can be added. In this case an explicit call to CMS_SignerInfo_sign() is -needed to finalize it. - -If B is set the signer's certificate will not be included in the -CMS_ContentInfo structure, the signer's certificate must still be supplied in -the B parameter though. This can reduce the size of the signature if -the signers certificate can be obtained by other means: for example a -previously signed message. - -The SignedData structure includes several CMS signedAttributes including the -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B is set then no signedAttributes -will be used. If B is set then just the SMIMECapabilities are -omitted. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B is set it will use the subject key -identifier value instead. An error occurs if the signing certificate does not -have a subject key identifier extension. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 -bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. -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 -not loaded. - -CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo -structure just added, this can be used to set additional attributes -before it is finalized. - -=head1 RETURN VALUES - -CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo -structure just added or NULL if an error occurs. - -=head1 SEE ALSO - -L, L, -L, - -=head1 HISTORY - -CMS_sign_add1_signer() was added to OpenSSL 0.9.8 - -=cut