Merge from vendor branch OPENSSL:
[dragonfly.git] / secure / lib / libcrypto / man / PKCS7_sign.3
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
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
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<>.
984263bc 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
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
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"
132.TH PKCS7_sign 3 "2004-12-18" "0.9.7e" "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
984263bc
MD
143PKCS#7 structure (for example any intermediate CAs in the chain).
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
MD
178of these algorithms is disabled then it will not be included.
179.SH "BUGS"
8b0cefbb
JR
180.IX Header "BUGS"
181\&\fIPKCS7_sign()\fR is somewhat limited. It does not support multiple signers, some
984263bc
MD
182advanced attributes such as counter signatures are not supported.
183.PP
8b0cefbb 184The \s-1SHA1\s0 digest algorithm is currently always used.
984263bc
MD
185.PP
186When the signed data is not detached it will be stored in memory within the
8b0cefbb 187\&\fB\s-1PKCS7\s0\fR structure. This effectively limits the size of messages which can be
984263bc
MD
188signed due to memory restraints. There should be a way to sign data without
189having to hold it all in memory, this would however require fairly major
8b0cefbb 190revisions of the OpenSSL \s-1ASN1\s0 code.
984263bc
MD
191.PP
192Clear text signing does not store the content in memory but the way \fIPKCS7_sign()\fR
193operates means that two passes of the data must typically be made: one to compute
194the signatures and a second to output the data along with the signature. There
195should be a way to process the data with only a single pass.
196.SH "RETURN VALUES"
8b0cefbb
JR
197.IX Header "RETURN VALUES"
198\&\fIPKCS7_sign()\fR returns either a valid \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error occurred.
984263bc
MD
199The error can be obtained from \fIERR_get_error\fR\|(3).
200.SH "SEE ALSO"
74dab6c2 201.IX Header "SEE ALSO"
8b0cefbb
JR
202\&\fIERR_get_error\fR\|(3), \fIPKCS7_verify\fR\|(3)
203.SH "HISTORY"
984263bc 204.IX Header "HISTORY"
8b0cefbb 205\&\fIPKCS7_sign()\fR was added to OpenSSL 0.9.5