| blob | aea1a265c2d547b7b29c348cd3034eefbfd0948c |
1 .\" $OpenBSD: PKCS7_sign.3,v 1.8 2018/03/22 16:06:33 schwarze Exp $
2 .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2002, 2003, 2006-2009, 2015 The OpenSSL Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: March 22 2018 $
53 .Dt PKCS7_SIGN 3
54 .Os
55 .Sh NAME
56 .Nm PKCS7_sign
57 .Nd create a PKCS#7 signedData structure
58 .Sh SYNOPSIS
59 .In openssl/pkcs7.h
60 .Ft PKCS7 *
61 .Fo PKCS7_sign
62 .Fa "X509 *signcert"
63 .Fa "EVP_PKEY *pkey"
64 .Fa "STACK_OF(X509) *certs"
65 .Fa "BIO *data"
66 .Fa "int flags"
67 .Fc
68 .Sh DESCRIPTION
69 .Fn PKCS7_sign
70 creates and returns a PKCS#7 signedData structure.
71 .Fa signcert
72 is the certificate to sign with,
73 .Fa pkey
74 is the corresponding private key.
75 .Fa certs
76 is an optional additional set of certificates to include in the PKCS#7
77 structure (for example any intermediate CAs in the chain).
78 .Pp
79 The data to be signed is read from
80 .Vt BIO
81 .Fa data .
82 .Pp
83 .Fa flags
84 is an optional set of flags.
85 .Pp
86 Any of the following flags (OR'ed together) can be passed in the
87 .Fa flags
88 parameter.
89 .Pp
90 Many S/MIME clients expect the signed content to include valid MIME
91 headers.
92 If the
93 .Dv PKCS7_TEXT
94 flag is set, MIME headers for type
95 .Sy text/plain
96 are prepended to the data.
97 .Pp
98 If
99 .Dv PKCS7_NOCERTS
100 is set, the signer's certificate will not be included in the PKCS7
101 structure, though the signer's certificate must still be supplied in the
102 .Fa signcert
103 parameter.
104 This can reduce the size of the signature if the signer's certificate can
105 be obtained by other means: for example a previously signed message.
106 .Pp
107 The data being signed is included in the
108 .Vt PKCS7
109 structure, unless
110 .Dv PKCS7_DETACHED
111 is set, in which case it is omitted.
112 This is used for PKCS7 detached signatures which are used in S/MIME
113 plaintext signed messages for example.
114 .Pp
115 Normally the supplied content is translated into MIME canonical format
116 (as required by the S/MIME specifications).
117 If
118 .Dv PKCS7_BINARY
119 is set, no translation occurs.
120 This option should be used if the supplied data is in binary format;
121 otherwise, the translation will corrupt it.
122 .Pp
123 The signedData structure includes several PKCS#7 authenticatedAttributes
124 including the signing time, the PKCS#7 content type and the supported
125 list of ciphers in an SMIMECapabilities attribute.
126 If
127 .Dv PKCS7_NOATTR
128 is set, then no authenticatedAttributes will be used.
129 If
130 .Dv PKCS7_NOSMIMECAP
131 is set, then just the SMIMECapabilities are omitted.
132 .Pp
133 If present, the SMIMECapabilities attribute indicates support for the
134 following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES
135 and 40-bit RC2.
136 If any of these algorithms is disabled then it will not be included.
137 .Pp
138 If the flags
139 .Dv PKCS7_STREAM
140 is set, then the returned
141 .Vt PKCS7
142 structure is just initialized ready to perform the signing operation.
143 The signing is however
144 .Sy not
145 performed and the data to be signed is not read from the
146 .Fa data
147 parameter.
148 Signing is deferred until after the data has been written.
149 In this way data can be signed in a single pass.
150 .Pp
151 If the
152 .Dv PKCS7_PARTIAL
153 flag is set, a partial
154 .Vt PKCS7
155 structure is output to which additional signers and capabilities can be
156 added before finalization.
157 .Pp
158 If the flag
159 .Dv PKCS7_STREAM
160 is set, the returned
161 .Vt PKCS7
162 structure is
163 .Sy not
164 complete and outputting its contents via a function that does not
165 properly finalize the
166 .Vt PKCS7
167 structure will give unpredictable results.
168 .Pp
169 Several functions, including
170 .Xr SMIME_write_PKCS7 3 ,
171 .Xr i2d_PKCS7_bio_stream 3 ,
172 and
173 .Xr PEM_write_bio_PKCS7_stream 3 ,
174 finalize the structure.
175 Alternatively finalization can be performed by obtaining the streaming
176 ASN.1
177 .Vt BIO
178 directly using
179 .Fn BIO_new_PKCS7 .
180 .Pp
181 If a signer is specified, it will use the default digest for the
182 signing algorithm.
183 This is
184 .Sy SHA1
185 for both RSA and DSA keys.
186 .Pp
187 In OpenSSL 1.0.0, the
188 .Fa certs ,
189 .Fa signcert ,
190 and
191 .Fa pkey
192 parameters can all be
193 .Dv NULL
194 if the
195 .Dv PKCS7_PARTIAL
196 flag is set.
197 One or more signers can be added using the function
198 .Xr PKCS7_sign_add_signer 3 .
199 .Fn PKCS7_final
200 must also be called to finalize the structure if streaming is not
201 enabled.
202 Alternative signing digests can also be specified using this method.
203 .Pp
204 In OpenSSL 1.0.0, if
205 .Fa signcert
206 and
207 .Fa pkey
208 are
209 .Dv NULL ,
210 then a certificate-only PKCS#7 structure is output.
211 .Pp
212 In versions of OpenSSL before 1.0.0 the
213 .Fa signcert
214 and
215 .Fa pkey
216 parameters must
217 .Sy NOT
218 be
219 .Dv NULL .
220 .Sh RETURN VALUES
221 .Fn PKCS7_sign
222 returns either a valid
223 .Vt PKCS7
224 structure or
225 .Dv NULL
226 if an error occurred.
227 The error can be obtained from
228 .Fn ERR_get_error 3 .
229 .Sh SEE ALSO
230 .Xr ERR_get_error 3 ,
231 .Xr PKCS7_new 3 ,
232 .Xr PKCS7_verify 3
233 .Sh HISTORY
234 .Fn PKCS7_sign
235 first appeared in OpenSSL 0.9.5 and have been available since
236 .Ox 2.7 .
237 .Pp
238 The
239 .Dv PKCS7_PARTIAL
240 and
241 .Dv PKCS7_STREAM
242 flags were added in OpenSSL 1.0.0.
243 .Sh BUGS
244 Some advanced attributes such as counter signatures are not supported.