From 0241f6701aac0e95428b9f0899b07ba086aa7e71 Mon Sep 17 00:00:00 2001
From: schwarze <>
Date: Wed, 11 Nov 2015 18:36:48 +0000
Subject: Convert and enable CMS manuals. Already some time ago, bcook@ said
 these can be installed.

---
 src/lib/libcrypto/man/CMS_decrypt.3 | 127 ++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 src/lib/libcrypto/man/CMS_decrypt.3

(limited to 'src/lib/libcrypto/man/CMS_decrypt.3')

diff --git a/src/lib/libcrypto/man/CMS_decrypt.3 b/src/lib/libcrypto/man/CMS_decrypt.3
new file mode 100644
index 0000000000..3a34f10783
--- /dev/null
+++ b/src/lib/libcrypto/man/CMS_decrypt.3
@@ -0,0 +1,127 @@
+.Dd $Mdocdate: November 11 2015 $
+.Dt CMS_DECRYPT 3
+.Os
+.Sh NAME
+.Nm CMS_decrypt
+.Nd decrypt content from a CMS envelopedData structure
+.Sh SYNOPSIS
+.In openssl/cms.h
+.Ft int
+.Fo CMS_decrypt
+.Fa "CMS_ContentInfo *cms"
+.Fa "EVP_PKEY *pkey"
+.Fa "X509 *cert"
+.Fa "BIO *dcont"
+.Fa "BIO *out"
+.Fa "unsigned int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn CMS_decrypt
+extracts and decrypts the content from a CMS EnvelopedData structure.
+.Fa pkey
+is the private key of the recipient,
+.Fa cert
+is the recipient's certificate,
+.Fa out
+is a
+.Vt BIO
+to write the content to and
+.Fa flags
+is an optional set of flags.
+.Pp
+The
+.Fa dcont
+parameter is used in the rare case where the encrypted content is
+detached.
+It will normally be set to
+.Dv NULL .
+.Sh NOTES
+.Xr OpenSSL_add_all_algorithms 3
+(or equivalent) should be called before using this function or errors
+about unknown algorithms will occur.
+.Pp
+Although the recipients certificate is not needed to decrypt the data it
+is needed to locate the appropriate (of possible several) recipients in
+the CMS structure.
+.Pp
+If
+.Fa cert
+is set to
+.Dv NULL ,
+all possible recipients are tried.
+This case however is problematic.
+To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA
+padding) all recipients are tried whether they succeed or not.
+If no recipient succeeds then a random symmetric key is used to decrypt
+the content: this will typically output garbage and may (but is not
+guaranteed to) ultimately return a padding error only.
+If
+.Fn CMS_decrypt
+just returned an error when all recipient encrypted keys failed to
+decrypt an attacker could use this in a timing attack.
+If the special flag
+.Dv CMS_DEBUG_DECRYPT
+is set then the above behaviour is modified and an error
+.Em is
+returned if no recipient encrypted key can be decrypted
+.Em without
+generating a random content encryption key.
+Applications should use this flag with
+.Sy extreme caution
+especially in automated gateways as it can leave them open to attack.
+.Pp
+It is possible to determine the correct recipient key by other means
+(for example looking them up in a database) and setting them in the CMS
+structure in advance using the CMS utility functions such as
+.Xr CMS_set1_pkey 3 .
+In this case both
+.Fa cert
+and
+.Fa pkey
+should be set to
+.Dv NULL .
+.Pp
+To process KEKRecipientInfo types
+.Xr CMS_set1_key 3
+or
+.Xr CMS_RecipientInfo_set0_key 3
+and
+.Xr CMS_ReceipientInfo_decrypt 3
+should be called before
+.Fn CMS_decrypt
+and
+.Fa cert
+and
+.Fa pkey
+set to
+.Dv NULL .
+.Pp
+The following flags can be passed in the
+.Fa flags
+parameter:
+.Pp
+If the
+.Dv CMS_TEXT
+flag is set MIME headers for type
+.Sy text/plain
+are deleted from the content.
+If the content is not of type
+.Sy text/plain
+then an error is returned.
+.Sh RETURN VALUES
+.Fn CMS_decrypt
+returns either 1 for success or 0 for failure.
+The error can be obtained from
+.Xr ERR_get_error 3 .
+.Sh BUGS
+The lack of single pass processing and the need to hold all data in
+memory as mentioned in
+.Xr CMS_verify 3
+also applies to
+.Fn CMS_decrypt .
+.Sh SEE ALSO
+.Xr CMS_encrypt 3 ,
+.Xr ERR_get_error 3
+.Sh HISTORY
+.Fn CMS_decrypt
+was added to OpenSSL 0.9.8.
-- 
cgit v1.2.3-55-g6feb