Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / PKCS7_sign.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "PKCS7_sign 3"
e3261593 127.TH PKCS7_sign 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133PKCS7_sign \- create a PKCS#7 signedData structure
134.SH "SYNOPSIS"
8b0cefbb 135.IX Header "SYNOPSIS"
01185282
PA
136.Vb 1
137\& #include <openssl/pkcs7.h>
138\&
139\& PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
140.Ve
984263bc 141.SH "DESCRIPTION"
8b0cefbb 142.IX Header "DESCRIPTION"
01185282
PA
143\&\fIPKCS7_sign()\fR creates and returns a PKCS#7 signedData structure. \fBsigncert\fR is
144the certificate to sign with, \fBpkey\fR is the corresponsding private key.
145\&\fBcerts\fR is an optional additional set of certificates to include in the PKCS#7
146structure (for example any intermediate CAs in the chain).
984263bc 147.PP
8b0cefbb 148The data to be signed is read from \s-1BIO\s0 \fBdata\fR.
984263bc 149.PP
8b0cefbb 150\&\fBflags\fR is an optional set of flags.
984263bc 151.SH "NOTES"
8b0cefbb 152.IX Header "NOTES"
01185282
PA
153Any of the following flags (ored together) can be passed in the \fBflags\fR
154parameter.
984263bc 155.PP
8b0cefbb
JR
156Many S/MIME clients expect the signed content to include valid \s-1MIME\s0 headers. If
157the \fB\s-1PKCS7_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are prepended
984263bc
MD
158to the data.
159.PP
8b0cefbb 160If \fB\s-1PKCS7_NOCERTS\s0\fR is set the signer's certificate will not be included in the
01185282
PA
161\&\s-1PKCS7\s0 structure, the signer's certificate must still be supplied in the
162\&\fBsigncert\fR parameter though. This can reduce the size of the signature if the
163signers certificate can be obtained by other means: for example a previously
164signed message.
984263bc 165.PP
01185282
PA
166The data being signed is included in the \s-1PKCS7\s0 structure, unless
167\&\fB\s-1PKCS7_DETACHED\s0\fR is set in which case it is omitted. This is used for \s-1PKCS7\s0
168detached signatures which are used in S/MIME plaintext signed messages for
169example.
984263bc 170.PP
01185282
PA
171Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
172required by the S/MIME specifications) if \fB\s-1PKCS7_BINARY\s0\fR is set no translation
173occurs. This option should be used if the supplied data is in binary format
174otherwise the translation will corrupt it.
984263bc 175.PP
01185282
PA
176The signedData structure includes several PKCS#7 autenticatedAttributes
177including the signing time, the PKCS#7 content type and the supported list of
178ciphers in an SMIMECapabilities attribute. If \fB\s-1PKCS7_NOATTR\s0\fR is set then no
179authenticatedAttributes will be used. If \fB\s-1PKCS7_NOSMIMECAP\s0\fR is set then just
180the SMIMECapabilities are omitted.
984263bc
MD
181.PP
182If present the SMIMECapabilities attribute indicates support for the following
01185282
PA
183algorithms: triple \s-1DES\s0, 128 bit \s-1RC2\s0, 64 bit \s-1RC2\s0, \s-1DES\s0 and 40 bit \s-1RC2\s0. If any of
184these algorithms is disabled then it will not be included.
185.PP
186If the flags \fB\s-1PKCS7_STREAM\s0\fR is set then the returned \fB\s-1PKCS7\s0\fR structure is
187just initialized ready to perform the signing operation. The signing is however
188\&\fBnot\fR performed and the data to be signed is not read from the \fBdata\fR
189parameter. Signing is deferred until after the data has been written. In this
190way data can be signed in a single pass.
191.PP
192If the \fB\s-1PKCS7_PARTIAL\s0\fR flag is set a partial \fB\s-1PKCS7\s0\fR structure is output to
193which additional signers and capabilities can be added before finalization.
a561f9ff
SS
194.SH "NOTES"
195.IX Header "NOTES"
01185282
PA
196If the flag \fB\s-1PKCS7_STREAM\s0\fR is set the returned \fB\s-1PKCS7\s0\fR structure is \fBnot\fR
197complete and outputting its contents via a function that does not properly
198finalize the \fB\s-1PKCS7\s0\fR structure will give unpredictable results.
984263bc 199.PP
01185282
PA
200Several functions including \fISMIME_write_PKCS7()\fR, \fIi2d_PKCS7_bio_stream()\fR,
201\&\fIPEM_write_bio_PKCS7_stream()\fR finalize the structure. Alternatively finalization
202can be performed by obtaining the streaming \s-1ASN1\s0 \fB\s-1BIO\s0\fR directly using
203\&\fIBIO_new_PKCS7()\fR.
984263bc 204.PP
01185282
PA
205If a signer is specified it will use the default digest for the signing
206algorithm. This is \fB\s-1SHA1\s0\fR for both \s-1RSA\s0 and \s-1DSA\s0 keys.
207.PP
208In OpenSSL 1.0.0 the \fBcerts\fR, \fBsigncert\fR and \fBpkey\fR parameters can all be
209\&\fB\s-1NULL\s0\fR if the \fB\s-1PKCS7_PARTIAL\s0\fR flag is set. One or more signers can be added
210using the function \fB\f(BIPKCS7_sign_add_signer()\fB\fR. \fB\f(BIPKCS7_final()\fB\fR must also be
211called to finalize the structure if streaming is not enabled. Alternative
212signing digests can also be specified using this method.
213.PP
214In OpenSSL 1.0.0 if \fBsigncert\fR and \fBpkey\fR are \s-1NULL\s0 then a certificates only
215PKCS#7 structure is output.
216.PP
217In versions of OpenSSL before 1.0.0 the \fBsigncert\fR and \fBpkey\fR parameters must
218\&\fB\s-1NOT\s0\fR be \s-1NULL\s0.
219.SH "BUGS"
220.IX Header "BUGS"
221Some advanced attributes such as counter signatures are not supported.
984263bc 222.SH "RETURN VALUES"
8b0cefbb 223.IX Header "RETURN VALUES"
01185282
PA
224\&\fIPKCS7_sign()\fR returns either a valid \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error
225occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
984263bc 226.SH "SEE ALSO"
74dab6c2 227.IX Header "SEE ALSO"
8b0cefbb
JR
228\&\fIERR_get_error\fR\|(3), \fIPKCS7_verify\fR\|(3)
229.SH "HISTORY"
984263bc 230.IX Header "HISTORY"
8b0cefbb 231\&\fIPKCS7_sign()\fR was added to OpenSSL 0.9.5
a561f9ff 232.PP
01185282
PA
233The \fB\s-1PKCS7_PARTIAL\s0\fR flag was added in OpenSSL 1.0.0
234.PP
235The \fB\s-1PKCS7_STREAM\s0\fR flag was added in OpenSSL 1.0.0