]>
Commit | Line | Data |
---|---|---|
0efb7b1e DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bb9ad09e | 5 | PKCS7_sign_add_signer - add a signer PKCS7 signed data structure |
0efb7b1e DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/pkcs7.h> | |
10 | ||
e9b77246 BB |
11 | PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, |
12 | EVP_PKEY *pkey, const EVP_MD *md, int flags); | |
0efb7b1e DSH |
13 | |
14 | ||
15 | =head1 DESCRIPTION | |
16 | ||
17 | PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private | |
18 | key B<pkey> using message digest B<md> to a PKCS7 signed data structure | |
19 | B<p7>. | |
20 | ||
21 | The PKCS7 structure should be obtained from an initial call to PKCS7_sign() | |
22 | with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 | |
23 | signed data structure. | |
24 | ||
25 | If the B<md> parameter is B<NULL> then the default digest for the public | |
26 | key algorithm will be used. | |
27 | ||
28 | Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure | |
29 | is not complete and must be finalized either by streaming (if applicable) or | |
30 | a call to PKCS7_final(). | |
31 | ||
32 | ||
33 | =head1 NOTES | |
34 | ||
35 | The main purpose of this function is to provide finer control over a PKCS#7 | |
36 | signed data structure where the simpler PKCS7_sign() function defaults are | |
37 | not appropriate. For example if multiple signers or non default digest | |
38 | algorithms are needed. | |
39 | ||
40 | Any of the following flags (ored together) can be passed in the B<flags> | |
41 | parameter. | |
42 | ||
43 | If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content | |
186bb907 | 44 | digest value from the PKCS7 structure: to add a signer to an existing structure. |
0efb7b1e DSH |
45 | An error occurs if a matching digest value cannot be found to copy. The |
46 | returned PKCS7 structure will be valid and finalized when this flag is set. | |
47 | ||
1bc74519 | 48 | If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the |
0efb7b1e DSH |
49 | B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes |
50 | can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is | |
51 | needed to finalize it. | |
52 | ||
53 | If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the | |
54 | PKCS7 structure, the signer's certificate must still be supplied in the | |
55 | B<signcert> parameter though. This can reduce the size of the signature if the | |
56 | signers certificate can be obtained by other means: for example a previously | |
57 | signed message. | |
58 | ||
27b138e9 | 59 | The signedData structure includes several PKCS#7 authenticatedAttributes |
0efb7b1e DSH |
60 | including the signing time, the PKCS#7 content type and the supported list of |
61 | ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no | |
62 | authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just | |
63 | the SMIMECapabilities are omitted. | |
64 | ||
65 | If present the SMIMECapabilities attribute indicates support for the following | |
66 | algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of | |
67 | these algorithms is disabled then it will not be included. | |
68 | ||
69 | ||
70 | PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO | |
1bc74519 | 71 | structure just added, this can be used to set additional attributes |
0efb7b1e DSH |
72 | before it is finalized. |
73 | ||
74 | =head1 RETURN VALUES | |
75 | ||
76 | PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO | |
77 | structure just added or NULL if an error occurs. | |
78 | ||
79 | =head1 SEE ALSO | |
80 | ||
9b86974e RS |
81 | L<ERR_get_error(3)>, L<PKCS7_sign(3)>, |
82 | L<PKCS7_final(3)>, | |
0efb7b1e DSH |
83 | |
84 | =head1 HISTORY | |
85 | ||
fc5ecadd | 86 | The PPKCS7_sign_add_signer() function was added in OpenSSL 1.0.0. |
0efb7b1e | 87 | |
e2f92610 RS |
88 | =head1 COPYRIGHT |
89 | ||
90 | Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved. | |
91 | ||
4746f25a | 92 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
93 | this file except in compliance with the License. You can obtain a copy |
94 | in the file LICENSE in the source distribution or at | |
95 | L<https://www.openssl.org/source/license.html>. | |
96 | ||
97 | =cut |