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 . 227