summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/doc/PKCS7_sign.pod
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/doc/PKCS7_sign.pod')
-rw-r--r--src/lib/libcrypto/doc/PKCS7_sign.pod115
1 files changed, 65 insertions, 50 deletions
diff --git a/src/lib/libcrypto/doc/PKCS7_sign.pod b/src/lib/libcrypto/doc/PKCS7_sign.pod
index ffd0c734b0..64a35144f8 100644
--- a/src/lib/libcrypto/doc/PKCS7_sign.pod
+++ b/src/lib/libcrypto/doc/PKCS7_sign.pod
@@ -6,14 +6,16 @@ PKCS7_sign - create a PKCS#7 signedData structure
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); 9 #include <openssl/pkcs7.h>
10
11 PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
10 12
11=head1 DESCRIPTION 13=head1 DESCRIPTION
12 14
13PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> 15PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
14is the certificate to sign with, B<pkey> is the corresponsding private key. 16the certificate to sign with, B<pkey> is the corresponsding private key.
15B<certs> is an optional additional set of certificates to include in the 17B<certs> is an optional additional set of certificates to include in the PKCS#7
16PKCS#7 structure (for example any intermediate CAs in the chain). 18structure (for example any intermediate CAs in the chain).
17 19
18The data to be signed is read from BIO B<data>. 20The data to be signed is read from BIO B<data>.
19 21
@@ -21,72 +23,83 @@ B<flags> is an optional set of flags.
21 23
22=head1 NOTES 24=head1 NOTES
23 25
24Any of the following flags (ored together) can be passed in the B<flags> parameter. 26Any of the following flags (ored together) can be passed in the B<flags>
27parameter.
25 28
26Many S/MIME clients expect the signed content to include valid MIME headers. If 29Many S/MIME clients expect the signed content to include valid MIME headers. If
27the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended 30the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
28to the data. 31to the data.
29 32
30If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the 33If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
31PKCS7 structure, the signer's certificate must still be supplied in the B<signcert> 34PKCS7 structure, the signer's certificate must still be supplied in the
32parameter though. This can reduce the size of the signature if the signers certificate 35B<signcert> parameter though. This can reduce the size of the signature if the
33can be obtained by other means: for example a previously signed message. 36signers certificate can be obtained by other means: for example a previously
34 37signed message.
35The data being signed is included in the PKCS7 structure, unless B<PKCS7_DETACHED> 38
36is set in which case it is omitted. This is used for PKCS7 detached signatures 39The data being signed is included in the PKCS7 structure, unless
37which are used in S/MIME plaintext signed messages for example. 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.
38 54
39Normally the supplied content is translated into MIME canonical format (as required 55If present the SMIMECapabilities attribute indicates support for the following
40by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This 56algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
41option should be used if the supplied data is in binary format otherwise the translation 57these algorithms is disabled then it will not be included.
42will corrupt it.
43 58
44The signedData structure includes several PKCS#7 autenticatedAttributes including 59If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
45the signing time, the PKCS#7 content type and the supported list of ciphers in 60just initialized ready to perform the signing operation. The signing is however
46an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes 61B<not> performed and the data to be signed is not read from the B<data>
47will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are 62parameter. Signing is deferred until after the data has been written. In this
48omitted. 63way data can be signed in a single pass.
49 64
50If present the SMIMECapabilities attribute indicates support for the following 65If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
51algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any 66which additional signers and capabilities can be added before finalization.
52of these algorithms is disabled then it will not be included.
53 67
54If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure
55is just initialized ready to perform the signing operation. The signing
56is however B<not> performed and the data to be signed is not read from
57the B<data> parameter. Signing is deferred until after the data has been
58written. In this way data can be signed in a single pass. Currently the
59flag B<PKCS7_DETACHED> B<must> also be set.
60 68
61=head1 NOTES 69=head1 NOTES
62 70
63Currently the flag B<PKCS7_PARTSIGN> is only supported for detached 71If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
64data. If this flag is set the returned B<PKCS7> structure is B<not> 72complete and outputting its contents via a function that does not properly
65complete and outputting its contents via a function that does not 73finalize the B<PKCS7> structure will give unpredictable results.
66properly finalize the B<PKCS7> structure will give unpredictable
67results.
68 74
69At present only the SMIME_write_PKCS7() function properly finalizes the 75Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
70structure. 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().
71 79
72=head1 BUGS 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.
73 88
74PKCS7_sign() is somewhat limited. It does not support multiple signers, some 89In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only
75advanced attributes such as counter signatures are not supported. 90PKCS#7 structure is output.
76 91
77The SHA1 digest algorithm is currently always used. 92In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
93B<NOT> be NULL.
78 94
79When the signed data is not detached it will be stored in memory within the 95=head1 BUGS
80B<PKCS7> structure. This effectively limits the size of messages which can be
81signed due to memory restraints. There should be a way to sign data without
82having to hold it all in memory, this would however require fairly major
83revisions of the OpenSSL ASN1 code.
84 96
97Some advanced attributes such as counter signatures are not supported.
85 98
86=head1 RETURN VALUES 99=head1 RETURN VALUES
87 100
88PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. 101PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
89The error can be obtained from ERR_get_error(3). 102occurred. The error can be obtained from ERR_get_error(3).
90 103
91=head1 SEE ALSO 104=head1 SEE ALSO
92 105
@@ -96,6 +109,8 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
96 109
97PKCS7_sign() was added to OpenSSL 0.9.5 110PKCS7_sign() was added to OpenSSL 0.9.5
98 111
99The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8 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
100 115
101=cut 116=cut