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