summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/CMS_add1_signer.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/CMS_add1_signer.3')
-rw-r--r--src/lib/libcrypto/man/CMS_add1_signer.3249
1 files changed, 0 insertions, 249 deletions
diff --git a/src/lib/libcrypto/man/CMS_add1_signer.3 b/src/lib/libcrypto/man/CMS_add1_signer.3
deleted file mode 100644
index 316d63c5ad..0000000000
--- a/src/lib/libcrypto/man/CMS_add1_signer.3
+++ /dev/null
@@ -1,249 +0,0 @@
1.\" $OpenBSD: CMS_add1_signer.3,v 1.10 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 is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2008 The OpenSSL Project. All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\" notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\" notice, this list of conditions and the following disclaimer in
33.\" the documentation and/or other materials provided with the
34.\" distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\" software must display the following acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\" endorse or promote products derived from this software without
43.\" prior written permission. For written permission, please contact
44.\" openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\" nor may "OpenSSL" appear in their names without prior written
48.\" permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\" acknowledgment:
52.\" "This product includes software developed by the OpenSSL Project
53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: April 18 2024 $
69.Dt CMS_ADD1_SIGNER 3
70.Os
71.Sh NAME
72.Nm CMS_add1_signer ,
73.Nm CMS_SignerInfo_sign
74.Nd add a signer to a CMS SignedData structure
75.Sh SYNOPSIS
76.In openssl/cms.h
77.Ft CMS_SignerInfo *
78.Fo CMS_add1_signer
79.Fa "CMS_ContentInfo *cms"
80.Fa "X509 *signcert"
81.Fa "EVP_PKEY *pkey"
82.Fa "const EVP_MD *md"
83.Fa "unsigned int flags"
84.Fc
85.Ft int
86.Fo CMS_SignerInfo_sign
87.Fa "CMS_SignerInfo *si"
88.Fc
89.Sh DESCRIPTION
90.Fn CMS_add1_signer
91adds a signer with certificate
92.Fa signcert
93and private key
94.Fa pkey
95using message digest
96.Fa md
97to the
98.Fa signerInfos
99field of the
100.Vt SignedData
101structure
102.Fa cms ,
103which should have been obtained from an initial call to
104.Xr CMS_sign 3
105with the flag
106.Dv CMS_PARTIAL
107set, or which can be a valid
108.Vt SignedData
109structure in the case of re-signing.
110.Pp
111If
112.Fa md
113is
114.Dv NULL ,
115the default digest for the public key algorithm of
116.Fa pkey
117is used.
118.Pp
119Unless the
120.Dv CMS_REUSE_DIGEST
121flag is set, the
122.Fa cms
123structure remains incomplete and must be finalized either by streaming
124(if applicable) or by a call to
125.Xr CMS_final 3 .
126.Pp
127The main purpose of
128.Fn CMS_add1_signer
129is to provide finer control over a CMS
130.Vt SignedData
131structure where the simpler
132.Xr CMS_sign 3
133function defaults are not appropriate, for example if multiple signers
134or non default digest algorithms are needed.
135New attributes can also be added using the returned
136.Vt CMS_SignerInfo
137structure and the CMS attribute utility functions or the CMS signed
138receipt request functions.
139.Pp
140Any of the following flags (OR'ed together) can be passed in the
141.Fa flags
142parameter:
143.Bl -tag -width Ds
144.It Dv CMS_REUSE_DIGEST
145Attempt to copy the content digest value from one of the existing
146.Vt CMS_SignerInfo
147structures in
148.Fa cms
149while adding another signer.
150An error occurs if a matching digest value cannot be found to copy.
151The
152.Fa cms
153structure will be valid and finalized when this flag is set.
154.It Dv CMS_PARTIAL
155If this flag is set in addition to
156.Dv CMS_REUSE_DIGEST ,
157the returned
158.Vt CMS_SignerInfo
159structure will not be finalized so additional attributes can be added.
160In this case an explicit call to
161.Fn CMS_SignerInfo_sign
162is needed to finalize it.
163.It Dv CMS_NOCERTS
164Do not add the signer's certificate to the
165.Fa certificates
166field of
167.Fa cms .
168The signer's certificate must still be supplied in the
169.Fa signcert
170parameter though.
171This flag can reduce the size of the signature if the signer's certificate can
172be obtained by other means, for example from a previously signed message.
173.It Dv CMS_NOATTR
174Leave the
175.Fa signedAttrs
176field of the returned
177.Vt CMS_SignedData
178structure empty.
179By default, several CMS
180.Vt SignedAttributes
181are added, including the signing time, the CMS content type,
182and the supported list of ciphers in an
183.Vt SMIMECapabilities
184attribute.
185.It Dv CMS_NOSMIMECAP
186Omit just the
187.Vt SMIMECapabilities
188attribute.
189.It Dv CMS_USE_KEYID
190Use the subject key identifier value to identify signing certificates.
191An error occurs if the signing certificate does not have a subject key
192identifier extension.
193By default, issuer name and serial number are used instead.
194.El
195.Pp
196If present, the
197.Vt SMIMECapabilities
198attribute indicates support for the
199following algorithms in preference order: 256-bit AES,
200192-bit AES, 128-bit AES, triple DES, 128-bit RC2, 64-bit
201RC2, DES and 40-bit RC2.
202If any of these algorithms is not available then it will not be
203included.
204.Pp
205The
206.Fn CMS_SignerInfo_sign
207function explicitly signs
208.Fa si .
209Its main use is when the
210.Dv CMS_REUSE_DIGEST
211and
212.Dv CMS_PARTIAL
213flags were both set in the call to
214.Fn CMS_add1_signer
215that created
216.Fa si .
217.Sh RETURN VALUES
218.Fn CMS_add1_signer
219returns an internal pointer to the new
220.Vt CMS_SignerInfo
221structure just added or
222.Dv NULL
223if an error occurs.
224.Sh SEE ALSO
225.Xr CMS_ContentInfo_new 3 ,
226.Xr CMS_final 3 ,
227.Xr CMS_sign 3 ,
228.Xr ERR_get_error 3
229.Sh STANDARDS
230RFC 5652: Cryptographic Message Syntax, section 5.1: SignedData Type
231.Pp
232RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures
233in the Cryptographic Message Syntax (CMS)
234.Pp
235RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME)
236Version\ 4.0 Message Specification
237.Bl -dash -compact -offset indent
238.It
239section 2.5: Attributes and the SignerInfo Type
240.It
241section 2.5.2: SMIMECapabilities Attribute
242.El
243.Sh HISTORY
244.Fn CMS_add1_signer
245and
246.Fn CMS_SignerInfo_sign
247first appeared in OpenSSL 0.9.8h
248and have been available since
249.Ox 6.7 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:45:55 +0000