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.3246
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
69creates and returns a CMS
70.Vt SignedData
71structure.
72.Fa signcert
73is the certificate to sign with,
74.Fa pkey
75is the corresponding private key.
76.Fa certs
77is an optional additional set of certificates to include in the CMS
78structure (for example any intermediate CAs in the chain).
79Any or all of these parameters can be
80.Dv NULL .
81.Pp
82The data to be signed is read from
83.Fa data .
84.Pp
85Any of the following flags (OR'ed together) can be passed in the
86.Fa flags
87argument:
88.Bl -tag -width Ds
89.It Dv CMS_TEXT
90Prepend MIME headers for the type text/plain to the data.
91Many S/MIME clients expect the signed content to include valid MIME
92headers.
93.It Dv CMS_NOCERTS
94Do not include the signer's certificate in the
95.Vt CMS_ContentInfo
96structure.
97The signer's certificate must still be supplied in the
98.Fa signcert
99parameter though.
100This can reduce the size of the signature if the signer's certificate can
101be obtained by other means, for example from a previously signed message.
102.It Dv CMS_DETACHED
103Omit the data being signed from the
104.Vt CMS_ContentInfo
105structure.
106This is used for
107.Vt CMS_ContentInfo
108detached signatures which are used in S/MIME plaintext signed messages
109for example.
110.It Dv CMS_BINARY
111Do not translate the supplied content into MIME canonical format
112even though that is required by the S/MIME specifications.
113This option should be used if the supplied data is in binary format.
114Otherwise the translation will corrupt it.
115.It Dv CMS_NOATTR
116Do not add any
117.Vt SignedAttributes .
118By default, the
119.Fa signerInfos
120field includes several CMS
121.Vt SignedAttributes
122including the signing time, the CMS content type,
123and the supported list of ciphers in an
124.Vt SMIMECapabilities
125attribute.
126.It Dv CMS_NOSMIMECAP
127Omit just the
128.Vt SMIMECapabilities .
129If present, the SMIMECapabilities attribute indicates support for the
130following algorithms in preference order: 256-bit AES,
131192-bit AES, 128-bit AES, triple DES, 128-bit RC2, 64-bit
132RC2, DES and 40-bit RC2.
133If any of these algorithms is not available, then it will not be
134included.
135.It Dv CMS_USE_KEYID
136Use the subject key identifier value to identify signing certificates.
137An error occurs if the signing certificate does not have a subject key
138identifier extension.
139By default, issuer name and serial number are used instead.
140.It Dv CMS_STREAM
141Only initialize the returned
142.Vt CMS_ContentInfo
143structure to prepare it for performing the signing operation.
144The signing is however
145.Em not
146performed and the data to be signed is not read from the
147.Fa data
148parameter.
149Signing is deferred until after the data has been written.
150In this way, data can be signed in a single pass.
151The returned
152.Vt CMS_ContentInfo
153structure is
154.Em not
155complete and outputting its contents via a function that does not
156properly finalize the
157.Vt CMS_ContentInfo
158structure will give unpredictable results.
159Several functions including
160.Xr SMIME_write_CMS 3 ,
161.Xr i2d_CMS_bio_stream 3 ,
162or
163.Xr PEM_write_bio_CMS_stream 3
164finalize the structure.
165Alternatively, finalization can be performed by obtaining the streaming
166ASN1
167.Vt BIO
168directly using
169.Xr BIO_new_CMS 3 .
170.It Dv CMS_PARTIAL
171Output a partial
172.Vt CMS_ContentInfo
173structure to which additional signers and capabilities can be
174added before finalization.
175.El
176.Pp
177If a signer is specified, it will use the default digest for the signing
178algorithm.
179This is SHA1 for both RSA and DSA keys.
180.Pp
181If
182.Fa signcert
183and
184.Fa pkey
185are
186.Dv NULL ,
187then a certificates only CMS structure is output.
188.Pp
189The function
190.Fn CMS_sign
191is a basic CMS signing function whose output will be suitable for many
192purposes.
193For finer control of the output format the
194.Fa certs ,
195.Fa signcert
196and
197.Fa pkey
198parameters can all be
199.Dv NULL
200and the
201.Dv CMS_PARTIAL
202flag set.
203Then one or more signers can be added using the function
204.Xr CMS_add1_signer 3 ,
205non default digests can be used and custom attributes added.
206.Xr CMS_final 3
207must then be called to finalize the structure if streaming is not
208enabled.
209.Sh RETURN VALUES
210.Fn CMS_sign
211returns either a valid
212.Vt CMS_ContentInfo
213structure or
214.Dv NULL
215if an error occurred.
216The 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
226RFC 5652: Cryptographic Message Syntax (CMS)
227.Bl -dash -compact -offset indent
228.It
229section 5.1: SignedData Type
230.It
231section 5.3: SignerInfo Type
232.El
233.Pp
234RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures
235in the Cryptographic Message Syntax (CMS)
236.Pp
237RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME)
238Version\ 4.0 Message Specification,
239section 2.5.2: SMIMECapabilities Attribute
240.Sh HISTORY
241.Fn CMS_sign
242first appeared in OpenSSL 0.9.8h
243and has been available since
244.Ox 6.7 .
245.Sh BUGS
246Some attributes such as counter signatures are not supported.