1.Dd $Mdocdate: November 11 2015 $ 2.Dt CMS_DECRYPT 3 3.Os 4.Sh NAME 5.Nm CMS_decrypt 6.Nd decrypt content from a CMS envelopedData structure 7.Sh SYNOPSIS 8.In openssl/cms.h 9.Ft int 10.Fo CMS_decrypt 11.Fa "CMS_ContentInfo *cms" 12.Fa "EVP_PKEY *pkey" 13.Fa "X509 *cert" 14.Fa "BIO *dcont" 15.Fa "BIO *out" 16.Fa "unsigned int flags" 17.Fc 18.Sh DESCRIPTION 19.Fn CMS_decrypt 20extracts and decrypts the content from a CMS EnvelopedData structure. 21.Fa pkey 22is the private key of the recipient, 23.Fa cert 24is the recipient's certificate, 25.Fa out 26is a 27.Vt BIO 28to write the content to and 29.Fa flags 30is an optional set of flags. 31.Pp 32The 33.Fa dcont 34parameter is used in the rare case where the encrypted content is 35detached. 36It will normally be set to 37.Dv NULL . 38.Sh NOTES 39.Xr OpenSSL_add_all_algorithms 3 40(or equivalent) should be called before using this function or errors 41about unknown algorithms will occur. 42.Pp 43Although the recipients certificate is not needed to decrypt the data it 44is needed to locate the appropriate (of possible several) recipients in 45the CMS structure. 46.Pp 47If 48.Fa cert 49is set to 50.Dv NULL , 51all possible recipients are tried. 52This case however is problematic. 53To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA 54padding) all recipients are tried whether they succeed or not. 55If no recipient succeeds then a random symmetric key is used to decrypt 56the content: this will typically output garbage and may (but is not 57guaranteed to) ultimately return a padding error only. 58If 59.Fn CMS_decrypt 60just returned an error when all recipient encrypted keys failed to 61decrypt an attacker could use this in a timing attack. 62If the special flag 63.Dv CMS_DEBUG_DECRYPT 64is set then the above behaviour is modified and an error 65.Em is 66returned if no recipient encrypted key can be decrypted 67.Em without 68generating a random content encryption key. 69Applications should use this flag with 70.Sy extreme caution 71especially in automated gateways as it can leave them open to attack. 72.Pp 73It is possible to determine the correct recipient key by other means 74(for example looking them up in a database) and setting them in the CMS 75structure in advance using the CMS utility functions such as 76.Xr CMS_set1_pkey 3 . 77In this case both 78.Fa cert 79and 80.Fa pkey 81should be set to 82.Dv NULL . 83.Pp 84To process KEKRecipientInfo types 85.Xr CMS_set1_key 3 86or 87.Xr CMS_RecipientInfo_set0_key 3 88and 89.Xr CMS_ReceipientInfo_decrypt 3 90should be called before 91.Fn CMS_decrypt 92and 93.Fa cert 94and 95.Fa pkey 96set to 97.Dv NULL . 98.Pp 99The following flags can be passed in the 100.Fa flags 101parameter: 102.Pp 103If the 104.Dv CMS_TEXT 105flag is set MIME headers for type 106.Sy text/plain 107are deleted from the content. 108If the content is not of type 109.Sy text/plain 110then an error is returned. 111.Sh RETURN VALUES 112.Fn CMS_decrypt 113returns either 1 for success or 0 for failure. 114The error can be obtained from 115.Xr ERR_get_error 3 . 116.Sh BUGS 117The lack of single pass processing and the need to hold all data in 118memory as mentioned in 119.Xr CMS_verify 3 120also applies to 121.Fn CMS_decrypt . 122.Sh SEE ALSO 123.Xr CMS_encrypt 3 , 124.Xr ERR_get_error 3 125.Sh HISTORY 126.Fn CMS_decrypt 127was added to OpenSSL 0.9.8. 128