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