diff options
author | cvs2svn <admin@example.com> | 2025-04-14 17:32:06 +0000 |
---|---|---|
committer | cvs2svn <admin@example.com> | 2025-04-14 17:32:06 +0000 |
commit | eb8dd9dca1228af0cd132f515509051ecfabf6f6 (patch) | |
tree | edb6da6af7e865d488dc1a29309f1e1ec226e603 /src/lib/libcrypto/man/CMS_sign.3 | |
parent | 247f0352e0ed72a4f476db9dc91f4d982bc83eb2 (diff) | |
download | openbsd-tb_20250414.tar.gz openbsd-tb_20250414.tar.bz2 openbsd-tb_20250414.zip |
This commit was manufactured by cvs2git to create tag 'tb_20250414'.tb_20250414
Diffstat (limited to 'src/lib/libcrypto/man/CMS_sign.3')
-rw-r--r-- | src/lib/libcrypto/man/CMS_sign.3 | 246 |
1 files changed, 0 insertions, 246 deletions
diff --git a/src/lib/libcrypto/man/CMS_sign.3 b/src/lib/libcrypto/man/CMS_sign.3 deleted file mode 100644 index 5261c190a6..0000000000 --- a/src/lib/libcrypto/man/CMS_sign.3 +++ /dev/null | |||
@@ -1,246 +0,0 @@ | |||
1 | .\" $OpenBSD: CMS_sign.3,v 1.11 2024/04/18 16:50:22 tb Exp $ | ||
2 | .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 | ||
3 | .\" | ||
4 | .\" This file was written by Dr. Stephen Henson <steve@openssl.org>. | ||
5 | .\" Copyright (c) 2008 The OpenSSL Project. All rights reserved. | ||
6 | .\" | ||
7 | .\" Redistribution and use in source and binary forms, with or without | ||
8 | .\" modification, are permitted provided that the following conditions | ||
9 | .\" are met: | ||
10 | .\" | ||
11 | .\" 1. Redistributions of source code must retain the above copyright | ||
12 | .\" notice, this list of conditions and the following disclaimer. | ||
13 | .\" | ||
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | ||
15 | .\" notice, this list of conditions and the following disclaimer in | ||
16 | .\" the documentation and/or other materials provided with the | ||
17 | .\" distribution. | ||
18 | .\" | ||
19 | .\" 3. All advertising materials mentioning features or use of this | ||
20 | .\" software must display the following acknowledgment: | ||
21 | .\" "This product includes software developed by the OpenSSL Project | ||
22 | .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" | ||
23 | .\" | ||
24 | .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to | ||
25 | .\" endorse or promote products derived from this software without | ||
26 | .\" prior written permission. For written permission, please contact | ||
27 | .\" openssl-core@openssl.org. | ||
28 | .\" | ||
29 | .\" 5. Products derived from this software may not be called "OpenSSL" | ||
30 | .\" nor may "OpenSSL" appear in their names without prior written | ||
31 | .\" permission of the OpenSSL Project. | ||
32 | .\" | ||
33 | .\" 6. Redistributions of any form whatsoever must retain the following | ||
34 | .\" acknowledgment: | ||
35 | .\" "This product includes software developed by the OpenSSL Project | ||
36 | .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" | ||
37 | .\" | ||
38 | .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY | ||
39 | .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
40 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
41 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR | ||
42 | .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
43 | .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | ||
44 | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
45 | .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||
46 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | ||
47 | .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | ||
48 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | ||
49 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. | ||
50 | .\" | ||
51 | .Dd $Mdocdate: April 18 2024 $ | ||
52 | .Dt CMS_SIGN 3 | ||
53 | .Os | ||
54 | .Sh NAME | ||
55 | .Nm CMS_sign | ||
56 | .Nd create a CMS SignedData structure | ||
57 | .Sh SYNOPSIS | ||
58 | .In openssl/cms.h | ||
59 | .Ft CMS_ContentInfo * | ||
60 | .Fo CMS_sign | ||
61 | .Fa "X509 *signcert" | ||
62 | .Fa "EVP_PKEY *pkey" | ||
63 | .Fa "STACK_OF(X509) *certs" | ||
64 | .Fa "BIO *data" | ||
65 | .Fa "unsigned int flags" | ||
66 | .Fc | ||
67 | .Sh DESCRIPTION | ||
68 | .Fn CMS_sign | ||
69 | creates and returns a CMS | ||
70 | .Vt SignedData | ||
71 | structure. | ||
72 | .Fa signcert | ||
73 | is the certificate to sign with, | ||
74 | .Fa pkey | ||
75 | is the corresponding private key. | ||
76 | .Fa certs | ||
77 | is an optional additional set of certificates to include in the CMS | ||
78 | structure (for example any intermediate CAs in the chain). | ||
79 | Any or all of these parameters can be | ||
80 | .Dv NULL . | ||
81 | .Pp | ||
82 | The data to be signed is read from | ||
83 | .Fa data . | ||
84 | .Pp | ||
85 | Any of the following flags (OR'ed together) can be passed in the | ||
86 | .Fa flags | ||
87 | argument: | ||
88 | .Bl -tag -width Ds | ||
89 | .It Dv CMS_TEXT | ||
90 | Prepend MIME headers for the type text/plain to the data. | ||
91 | Many S/MIME clients expect the signed content to include valid MIME | ||
92 | headers. | ||
93 | .It Dv CMS_NOCERTS | ||
94 | Do not include the signer's certificate in the | ||
95 | .Vt CMS_ContentInfo | ||
96 | structure. | ||
97 | The signer's certificate must still be supplied in the | ||
98 | .Fa signcert | ||
99 | parameter though. | ||
100 | This can reduce the size of the signature if the signer's certificate can | ||
101 | be obtained by other means, for example from a previously signed message. | ||
102 | .It Dv CMS_DETACHED | ||
103 | Omit the data being signed from the | ||
104 | .Vt CMS_ContentInfo | ||
105 | structure. | ||
106 | This is used for | ||
107 | .Vt CMS_ContentInfo | ||
108 | detached signatures which are used in S/MIME plaintext signed messages | ||
109 | for example. | ||
110 | .It Dv CMS_BINARY | ||
111 | Do not translate the supplied content into MIME canonical format | ||
112 | even though that is required by the S/MIME specifications. | ||
113 | This option should be used if the supplied data is in binary format. | ||
114 | Otherwise the translation will corrupt it. | ||
115 | .It Dv CMS_NOATTR | ||
116 | Do not add any | ||
117 | .Vt SignedAttributes . | ||
118 | By default, the | ||
119 | .Fa signerInfos | ||
120 | field includes several CMS | ||
121 | .Vt SignedAttributes | ||
122 | including the signing time, the CMS content type, | ||
123 | and the supported list of ciphers in an | ||
124 | .Vt SMIMECapabilities | ||
125 | attribute. | ||
126 | .It Dv CMS_NOSMIMECAP | ||
127 | Omit just the | ||
128 | .Vt SMIMECapabilities . | ||
129 | If present, the SMIMECapabilities attribute indicates support for the | ||
130 | following algorithms in preference order: 256-bit AES, | ||
131 | 192-bit AES, 128-bit AES, triple DES, 128-bit RC2, 64-bit | ||
132 | RC2, DES and 40-bit RC2. | ||
133 | If any of these algorithms is not available, then it will not be | ||
134 | included. | ||
135 | .It Dv CMS_USE_KEYID | ||
136 | Use the subject key identifier value to identify signing certificates. | ||
137 | An error occurs if the signing certificate does not have a subject key | ||
138 | identifier extension. | ||
139 | By default, issuer name and serial number are used instead. | ||
140 | .It Dv CMS_STREAM | ||
141 | Only initialize the returned | ||
142 | .Vt CMS_ContentInfo | ||
143 | structure to prepare it for performing the signing operation. | ||
144 | The signing is however | ||
145 | .Em not | ||
146 | performed and the data to be signed is not read from the | ||
147 | .Fa data | ||
148 | parameter. | ||
149 | Signing is deferred until after the data has been written. | ||
150 | In this way, data can be signed in a single pass. | ||
151 | The returned | ||
152 | .Vt CMS_ContentInfo | ||
153 | structure is | ||
154 | .Em not | ||
155 | complete and outputting its contents via a function that does not | ||
156 | properly finalize the | ||
157 | .Vt CMS_ContentInfo | ||
158 | structure will give unpredictable results. | ||
159 | Several functions including | ||
160 | .Xr SMIME_write_CMS 3 , | ||
161 | .Xr i2d_CMS_bio_stream 3 , | ||
162 | or | ||
163 | .Xr PEM_write_bio_CMS_stream 3 | ||
164 | finalize the structure. | ||
165 | Alternatively, finalization can be performed by obtaining the streaming | ||
166 | ASN1 | ||
167 | .Vt BIO | ||
168 | directly using | ||
169 | .Xr BIO_new_CMS 3 . | ||
170 | .It Dv CMS_PARTIAL | ||
171 | Output a partial | ||
172 | .Vt CMS_ContentInfo | ||
173 | structure to which additional signers and capabilities can be | ||
174 | added before finalization. | ||
175 | .El | ||
176 | .Pp | ||
177 | If a signer is specified, it will use the default digest for the signing | ||
178 | algorithm. | ||
179 | This is SHA1 for both RSA and DSA keys. | ||
180 | .Pp | ||
181 | If | ||
182 | .Fa signcert | ||
183 | and | ||
184 | .Fa pkey | ||
185 | are | ||
186 | .Dv NULL , | ||
187 | then a certificates only CMS structure is output. | ||
188 | .Pp | ||
189 | The function | ||
190 | .Fn CMS_sign | ||
191 | is a basic CMS signing function whose output will be suitable for many | ||
192 | purposes. | ||
193 | For finer control of the output format the | ||
194 | .Fa certs , | ||
195 | .Fa signcert | ||
196 | and | ||
197 | .Fa pkey | ||
198 | parameters can all be | ||
199 | .Dv NULL | ||
200 | and the | ||
201 | .Dv CMS_PARTIAL | ||
202 | flag set. | ||
203 | Then one or more signers can be added using the function | ||
204 | .Xr CMS_add1_signer 3 , | ||
205 | non default digests can be used and custom attributes added. | ||
206 | .Xr CMS_final 3 | ||
207 | must then be called to finalize the structure if streaming is not | ||
208 | enabled. | ||
209 | .Sh RETURN VALUES | ||
210 | .Fn CMS_sign | ||
211 | returns either a valid | ||
212 | .Vt CMS_ContentInfo | ||
213 | structure or | ||
214 | .Dv NULL | ||
215 | if an error occurred. | ||
216 | The error can be obtained from | ||
217 | .Xr ERR_get_error 3 . | ||
218 | .Sh SEE ALSO | ||
219 | .Xr CMS_add0_cert 3 , | ||
220 | .Xr CMS_add1_signer 3 , | ||
221 | .Xr CMS_ContentInfo_new 3 , | ||
222 | .Xr CMS_final 3 , | ||
223 | .Xr CMS_sign_receipt 3 , | ||
224 | .Xr CMS_verify 3 | ||
225 | .Sh STANDARDS | ||
226 | RFC 5652: Cryptographic Message Syntax (CMS) | ||
227 | .Bl -dash -compact -offset indent | ||
228 | .It | ||
229 | section 5.1: SignedData Type | ||
230 | .It | ||
231 | section 5.3: SignerInfo Type | ||
232 | .El | ||
233 | .Pp | ||
234 | RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures | ||
235 | in the Cryptographic Message Syntax (CMS) | ||
236 | .Pp | ||
237 | RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) | ||
238 | Version\ 4.0 Message Specification, | ||
239 | section 2.5.2: SMIMECapabilities Attribute | ||
240 | .Sh HISTORY | ||
241 | .Fn CMS_sign | ||
242 | first appeared in OpenSSL 0.9.8h | ||
243 | and has been available since | ||
244 | .Ox 6.7 . | ||
245 | .Sh BUGS | ||
246 | Some attributes such as counter signatures are not supported. | ||