Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / PKCS7_sign.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH PKCS7_sign 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191PKCS7_sign \- create a PKCS#7 signedData structure
192.SH "SYNOPSIS"
74dab6c2 193PKCS7 *\fIPKCS7_sign\fR\|(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
984263bc 194.SH "DESCRIPTION"
74dab6c2 195\fIPKCS7_sign()\fR creates and returns a PKCS#7 signedData structure. \fBsigncert\fR
984263bc 196is the certificate to sign with, \fBpkey\fR is the corresponsding private key.
74dab6c2 197\fBcerts\fR is an optional additional set of certificates to include in the
984263bc
MD
198PKCS#7 structure (for example any intermediate CAs in the chain).
199.PP
74dab6c2 200The data to be signed is read from BIO \fBdata\fR.
984263bc 201.PP
74dab6c2 202\fBflags\fR is an optional set of flags.
984263bc 203.SH "NOTES"
984263bc
MD
204Any of the following flags (ored together) can be passed in the \fBflags\fR parameter.
205.PP
74dab6c2
JR
206Many S/MIME clients expect the signed content to include valid MIME headers. If
207the \fBPKCS7_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are prepended
984263bc
MD
208to the data.
209.PP
74dab6c2
JR
210If \fBPKCS7_NOCERTS\fR is set the signer's certificate will not be included in the
211PKCS7 structure, the signer's certificate must still be supplied in the \fBsigncert\fR
984263bc
MD
212parameter though. This can reduce the size of the signature if the signers certificate
213can be obtained by other means: for example a previously signed message.
214.PP
74dab6c2
JR
215The data being signed is included in the PKCS7 structure, unless \fBPKCS7_DETACHED\fR
216is set in which case it is omitted. This is used for PKCS7 detached signatures
984263bc
MD
217which are used in S/MIME plaintext signed messages for example.
218.PP
74dab6c2
JR
219Normally the supplied content is translated into MIME canonical format (as required
220by the S/MIME specifications) if \fBPKCS7_BINARY\fR is set no translation occurs. This
984263bc
MD
221option should be used if the supplied data is in binary format otherwise the translation
222will corrupt it.
223.PP
224The signedData structure includes several PKCS#7 autenticatedAttributes including
225the signing time, the PKCS#7 content type and the supported list of ciphers in
74dab6c2
JR
226an SMIMECapabilities attribute. If \fBPKCS7_NOATTR\fR is set then no authenticatedAttributes
227will be used. If \fBPKCS7_NOSMIMECAP\fR is set then just the SMIMECapabilities are
984263bc
MD
228omitted.
229.PP
230If present the SMIMECapabilities attribute indicates support for the following
74dab6c2 231algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any
984263bc
MD
232of these algorithms is disabled then it will not be included.
233.SH "BUGS"
74dab6c2 234\fIPKCS7_sign()\fR is somewhat limited. It does not support multiple signers, some
984263bc
MD
235advanced attributes such as counter signatures are not supported.
236.PP
74dab6c2 237The SHA1 digest algorithm is currently always used.
984263bc
MD
238.PP
239When the signed data is not detached it will be stored in memory within the
74dab6c2 240\fBPKCS7\fR structure. This effectively limits the size of messages which can be
984263bc
MD
241signed due to memory restraints. There should be a way to sign data without
242having to hold it all in memory, this would however require fairly major
74dab6c2 243revisions of the OpenSSL ASN1 code.
984263bc
MD
244.PP
245Clear text signing does not store the content in memory but the way \fIPKCS7_sign()\fR
246operates means that two passes of the data must typically be made: one to compute
247the signatures and a second to output the data along with the signature. There
248should be a way to process the data with only a single pass.
249.SH "RETURN VALUES"
74dab6c2 250\fIPKCS7_sign()\fR returns either a valid PKCS7 structure or NULL if an error occurred.
984263bc
MD
251The error can be obtained from \fIERR_get_error\fR\|(3).
252.SH "SEE ALSO"
984263bc
MD
253ERR_get_error(3), PKCS7_verify(3)
254.SH "HISTORY"
74dab6c2
JR
255\fIPKCS7_sign()\fR was added to OpenSSL 0.9.5
256
257.rn }` ''
258.IX Title "PKCS7_sign 3"
259.IX Name "PKCS7_sign - create a PKCS#7 signedData structure"
260
261.IX Header "NAME"
262
263.IX Header "SYNOPSIS"
264
265.IX Header "DESCRIPTION"
266
267.IX Header "NOTES"
268
269.IX Header "BUGS"
270
271.IX Header "RETURN VALUES"
272
273.IX Header "SEE ALSO"
274
984263bc 275.IX Header "HISTORY"
74dab6c2 276