summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/CMS_decrypt.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/CMS_decrypt.3')
-rw-r--r--src/lib/libcrypto/man/CMS_decrypt.3226
1 files changed, 0 insertions, 226 deletions
diff --git a/src/lib/libcrypto/man/CMS_decrypt.3 b/src/lib/libcrypto/man/CMS_decrypt.3
deleted file mode 100644
index 243ab2f30e..0000000000
--- a/src/lib/libcrypto/man/CMS_decrypt.3
+++ /dev/null
@@ -1,226 +0,0 @@
1.\" $OpenBSD: CMS_decrypt.3,v 1.8 2019/11/02 15:39:46 schwarze 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, 2014 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: November 2 2019 $
69.Dt CMS_DECRYPT 3
70.Os
71.Sh NAME
72.Nm CMS_decrypt ,
73.Nm CMS_decrypt_set1_pkey ,
74.Nm CMS_decrypt_set1_key
75.Nd decrypt content from a CMS EnvelopedData structure
76.Sh SYNOPSIS
77.In openssl/cms.h
78.Ft int
79.Fo CMS_decrypt
80.Fa "CMS_ContentInfo *cms"
81.Fa "EVP_PKEY *private_key"
82.Fa "X509 *certificate"
83.Fa "BIO *dcont"
84.Fa "BIO *out"
85.Fa "unsigned int flags"
86.Fc
87.Ft int
88.Fo CMS_decrypt_set1_pkey
89.Fa "CMS_ContentInfo *cms"
90.Fa "EVP_PKEY *private_key"
91.Fa "X509 *certificate"
92.Fc
93.Ft int
94.Fo CMS_decrypt_set1_key
95.Fa "CMS_ContentInfo *cms"
96.Fa "unsigned char *symmetric_key"
97.Fa "size_t keylen"
98.Fa "const unsigned char *id"
99.Fa "size_t idlen"
100.Fc
101.Sh DESCRIPTION
102.Fn CMS_decrypt
103extracts and decrypts the content from the CMS
104.Vt EnvelopedData
105structure
106.Fa cms
107using the
108.Fa private_key
109and the
110.Fa certificate
111of the recipient.
112It writes the decrypted content to
113.Fa out .
114.Pp
115In the rare case where the compressed content is detached, pass it in via
116.Fa dcont .
117For normal use, set
118.Fa dcont
119to
120.Dv NULL .
121.Pp
122Although the recipient's
123.Fa certificate
124is not needed to decrypt the data, it is needed to locate the
125appropriate (of possibly several) recipients in the CMS structure.
126.Pp
127If the
128.Fa certificate
129is set to
130.Dv NULL ,
131all possible recipients are tried.
132This case however is problematic.
133To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA
134padding), all recipients are tried whether they succeed or not.
135If no recipient succeeds, a random symmetric key is used to decrypt
136the content: this will typically output garbage and may (but is not
137guaranteed to) ultimately return a padding error only.
138If
139.Fn CMS_decrypt
140just returned an error when all recipient encrypted keys failed to
141decrypt, an attacker could use this in a timing attack.
142If the special flag
143.Dv CMS_DEBUG_DECRYPT
144is set, the above behaviour is modified and an error
145.Em is
146returned if no recipient encrypted key can be decrypted
147.Em without
148generating a random content encryption key.
149Applications should use this flag with extreme caution
150especially in automated gateways as it can leave them open to attack.
151.Pp
152It is possible to determine the correct recipient key by other means
153(for example by looking them up in a database) and setting them in the
154.Fa cms
155structure in advance using the CMS utility functions such as
156.Fn CMS_decrypt_set1_pkey .
157In this case both
158.Fa certificate
159and
160.Fa private_key
161should be set to
162.Dv NULL
163when calling
164.Fn CMS_decrypt
165later on.
166.Pp
167To process
168.Vt KEKRecipientInfo
169types,
170.Fn CMS_decrypt_set1_key
171or
172.Xr CMS_RecipientInfo_set0_key 3
173and
174.Xr CMS_RecipientInfo_decrypt 3
175should be called before
176.Fn CMS_decrypt
177and
178.Fa certificate
179and
180.Fa private_key
181set to
182.Dv NULL
183when calling
184.Fn CMS_decrypt
185later on.
186.Pp
187If the
188.Dv CMS_TEXT
189bit is set in
190.Fa flags ,
191MIME headers for type text/plain are deleted from the content.
192If the content is not of type text/plain, an error occurs.
193.Sh RETURN VALUES
194.Fn CMS_decrypt ,
195.Fn CMS_decrypt_set1_pkey ,
196and
197.Fn CMS_decrypt_set1_key
198return 1 for success or 0 for failure.
199The error can be obtained from
200.Xr ERR_get_error 3 .
201.Sh SEE ALSO
202.Xr CMS_ContentInfo_new 3 ,
203.Xr CMS_encrypt 3 ,
204.Xr CMS_get0_RecipientInfos 3
205.Sh STANDARDS
206RFC 5652: Cryptographic Message Syntax (CMS)
207.Bl -dash -compact -offset indent
208.It
209section 6.1: EnvelopedData Type
210.It
211section 6.2.3: KEKRecipientInfo Type
212.El
213.Sh HISTORY
214.Fn CMS_decrypt ,
215.Fn CMS_decrypt_set1_pkey ,
216and
217.Fn CMS_decrypt_set1_key
218first appeared in OpenSSL 0.9.8h
219and have been available since
220.Ox 6.7 .
221.Sh BUGS
222The lack of single pass processing and the need to hold all data in
223memory as mentioned in
224.Xr CMS_verify 3
225also applies to
226.Fn CMS_decrypt .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 23:10:22 +0000