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