summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/CMS_sign.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/CMS_sign.3199
1 files changed, 0 insertions, 199 deletions
diff --git a/src/lib/libcrypto/man/CMS_sign.3 b/src/lib/libcrypto/man/CMS_sign.3
deleted file mode 100644
index af75a20d6b..0000000000
--- a/src/lib/libcrypto/man/CMS_sign.3
+++ /dev/null
@@ -1,199 +0,0 @@
1.Dd $Mdocdate: November 11 2015 $
2.Dt CMS_SIGN 3
3.Os
4.Sh NAME
5.Nm CMS_sign
6.Nd create a CMS SignedData structure
7.Sh SYNOPSIS
8.In openssl/cms.h
9.Ft CMS_ContentInfo *
10.Fo CMS_sign
11.Fa "X509 *signcert"
12.Fa "EVP_PKEY *pkey"
13.Fa "STACK_OF(X509) *certs"
14.Fa "BIO *data"
15.Fa "unsigned int flags"
16.Fc
17.Sh DESCRIPTION
18.Fn CMS_sign
19creates and returns a CMS SignedData structure.
20.Fa signcert
21is the certificate to sign with,
22.Fa pkey
23is the corresponding private key.
24.Fa certs
25is an optional additional set of certificates to include in the CMS
26structure (for example any intermediate CAs in the chain).
27Any or all of these parameters can be
28.Dv NULL ,
29see
30.Sx NOTES
31below.
32.Pp
33The data to be signed is read from
34.Fa data .
35.Pp
36.Fa flags
37is an optional set of flags.
38.Sh NOTES
39Any of the following flags (OR'ed together) can be passed in the
40.Fa flags
41parameter.
42.Pp
43Many S/MIME clients expect the signed content to include valid MIME
44headers.
45If the
46.Dv CMS_TEXT
47flag is set, MIME headers for type
48.Sy text/plain
49are prepended to the data.
50.Pp
51If
52.Dv CMS_NOCERTS
53is set, the signer's certificate will not be included in the
54.Vt CMS_ContentInfo
55structure, the signer's certificate must still be supplied in the
56.Fa signcert
57parameter though.
58This can reduce the size of the signature if the signers certificate can
59be obtained by other means: for example a previously signed message.
60.Pp
61The data being signed is included in the
62.Vt CMS_ContentInfo
63structure, unless
64.Dv CMS_DETACHED
65is set, in which case it is omitted.
66This is used for
67.Vt CMS_ContentInfo
68detached signatures which are used in S/MIME plaintext signed
69messages for example.
70.Pp
71Normally the supplied content is translated into MIME canonical format
72(as required by the S/MIME specifications); if
73.Dv CMS_BINARY
74is set, no translation occurs.
75This option should be used if the supplied data is in binary format;
76otherwise the translation will corrupt it.
77.Pp
78The SignedData structure includes several CMS signedAttributes including
79the signing time, the CMS content type and the supported list of ciphers
80in an SMIMECapabilities attribute.
81If
82.Dv CMS_NOATTR
83is set, then no signedAttributes will be used.
84If
85.Dv CMS_NOSMIMECAP
86is set, then just the SMIMECapabilities are omitted.
87.Pp
88If present, the SMIMECapabilities attribute indicates support for the
89following algorithms in preference order: 256 bit AES, Gost R3411-94,
90Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit
91RC2, DES and 40 bit RC2.
92If any of these algorithms is not available, then it will not be
93included: for example the GOST algorithms will not be included if
94the GOST ENGINE is not loaded.
95.Pp
96OpenSSL will by default identify signing certificates using issuer name
97and serial number.
98If
99.Dv CMS_USE_KEYID
100is set, it will use the subject key identifier value instead.
101An error occurs if the signing certificate does not have a subject key
102identifier extension.
103.Pp
104If the flag
105.Dv CMS_STREAM
106is set, then the returned
107.Vt CMS_ContentInfo
108structure is just initialized ready to perform the signing operation.
109The signing is however
110.Em not
111performed and the data to be signed is not read from the
112.Fa data
113parameter.
114Signing is deferred until after the data has been written.
115In this way, data can be signed in a single pass.
116.Pp
117If the
118.Dv CMS_PARTIAL
119flag is set, a partial
120.Vt CMS_ContentInfo
121structure is output to which additional signers and capabilities can be
122added before finalization.
123.Pp
124If the flag
125.Dv CMS_STREAM
126is set, the returned
127.Vt CMS_ContentInfo
128structure is
129.Em not
130complete and outputting its contents via a function that does not
131properly finalize the
132.Vt CMS_ContentInfo
133structure will give unpredictable results.
134.Pp
135Several functions including
136.Xr SMIME_write_CMS 3 ,
137.Xr i2d_CMS_bio_stream 3 ,
138.Xr PEM_write_bio_CMS_stream 3
139finalize the structure.
140Alternatively finalization can be performed by obtaining the streaming
141ASN1
142.Vt BIO
143directly using
144.Xr BIO_new_CMS 3 .
145.Pp
146If a signer is specified, it will use the default digest for the signing
147algorithm.
148This is SHA1 for both RSA and DSA keys.
149.Pp
150If
151.Fa signcert
152and
153.Fa pkey
154are
155.Dv NULL ,
156then a certificates only CMS structure is output.
157.Pp
158The function
159.Fn CMS_sign
160is a basic CMS signing function whose output will be suitable for many
161purposes.
162For finer control of the output format the
163.Fa certs ,
164.Fa signcert
165and
166.Fa pkey
167parameters can all be
168.Dv NULL
169and the
170.Dv CMS_PARTIAL
171flag set.
172Then one or more signers can be added using the function
173.Xr CMS_sign_add1_signer 3 ,
174non default digests can be used and custom attributes added.
175.Xr CMS_final 3
176must then be called to finalize the structure if streaming is not
177enabled.
178.Sh RETURN VALUES
179.Fn CMS_sign
180returns either a valid
181.Vt CMS_ContentInfo
182structure or
183.Dv NULL
184if an error occurred.
185The error can be obtained from
186.Xr ERR_get_error 3 .
187.Sh SEE ALSO
188.Xr CMS_verify 3 ,
189.Xr ERR_get_error 3
190.Sh HISTORY
191.Fn CMS_sign
192was added to OpenSSL 0.9.8.
193.Pp
194The
195.Dv CMS_STREAM
196flag is only supported for detached data in OpenSSL 0.9.8.
197It is supported for embedded data in OpenSSL 1.0.0 and later.
198.Sh BUGS
199Some attributes such as counter signatures are not supported.