1=pod
2
3=head1 NAME
4
5PKCS7_sign - create a PKCS#7 signedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
12
13=head1 DESCRIPTION
14
15PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
16the certificate to sign with, B<pkey> is the corresponsding private key.
17B<certs> is an optional additional set of certificates to include in the PKCS#7
18structure (for example any intermediate CAs in the chain). 
19
20The data to be signed is read from BIO B<data>.
21
22B<flags> is an optional set of flags.
23
24=head1 NOTES
25
26Any of the following flags (ored together) can be passed in the B<flags>
27parameter.
28
29Many S/MIME clients expect the signed content to include valid MIME headers. If
30the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
31to the data.
32
33If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
34PKCS7 structure, the signer's certificate must still be supplied in the
35B<signcert> parameter though. This can reduce the size of the signature if the
36signers certificate can be obtained by other means: for example a previously
37signed message.
38
39The data being signed is included in the PKCS7 structure, unless
40B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7
41detached signatures which are used in S/MIME plaintext signed messages for
42example.
43
44Normally the supplied content is translated into MIME canonical format (as
45required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
46occurs. This option should be used if the supplied data is in binary format
47otherwise the translation will corrupt it.
48
49The signedData structure includes several PKCS#7 autenticatedAttributes
50including the signing time, the PKCS#7 content type and the supported list of
51ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
52authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
53the SMIMECapabilities are omitted.
54
55If present the SMIMECapabilities attribute indicates support for the following
56algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
57these algorithms is disabled then it will not be included.
58
59If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
60just initialized ready to perform the signing operation. The signing is however
61B<not> performed and the data to be signed is not read from the B<data>
62parameter. Signing is deferred until after the data has been written. In this
63way data can be signed in a single pass.
64
65If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
66which additional signers and capabilities can be added before finalization.
67
68
69=head1 NOTES
70
71If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
72complete and outputting its contents via a function that does not properly
73finalize the B<PKCS7> structure will give unpredictable results.
74
75Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
76PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
77can be performed by obtaining the streaming ASN1 B<BIO> directly using
78BIO_new_PKCS7().
79
80If a signer is specified it will use the default digest for the signing
81algorithm. This is B<SHA1> for both RSA and DSA keys.
82
83In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be
84B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
85using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be
86called to finalize the structure if streaming is not enabled. Alternative
87signing digests can also be specified using this method.
88
89In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only
90PKCS#7 structure is output.
91
92In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
93B<NOT> be NULL.
94
95=head1 BUGS
96
97Some advanced attributes such as counter signatures are not supported.
98
99=head1 RETURN VALUES
100
101PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
102occurred.  The error can be obtained from ERR_get_error(3).
103
104=head1 SEE ALSO
105
106L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
107
108=head1 HISTORY
109
110PKCS7_sign() was added to OpenSSL 0.9.5
111
112The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0
113
114The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0
115
116=cut
117