Reject calls to X509_verify_cert that have not been reinitialised

[openssl.git] / doc / crypto / CMS_get0_RecipientInfos.pod

diff --git a/doc/crypto/CMS_get0_RecipientInfos.pod b/doc/crypto/CMS_get0_RecipientInfos.pod
index fa6957489323060cc3d5c950f0e56384a92d8560..fe49772a86a6bd7e7cd4fc589e7f135258f5e6a3 100644 (file)
--- a/doc/crypto/CMS_get0_RecipientInfos.pod
+++ b/doc/crypto/CMS_get0_RecipientInfos.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
+CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines
 
 =head1 SYNOPSIS
 
@@ -20,11 +20,12 @@ CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_sig
  int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
 
  int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
+ int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
 
 =head1 DESCRIPTION
 
 The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
-structures associated with a CMS envelopedData structure.
+structures associated with a CMS EnvelopedData structure.
 
 CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
 It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
@@ -35,7 +36,7 @@ identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
 must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
 B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. 
 
-CMS_RecipientInfo_ktri_cert_cmp() compares the cerificate B<cert> against the
+CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
 CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
 It returns zero if the comparison is successful and non zero if not.
 
@@ -66,6 +67,11 @@ CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
 B<ri> in structure B<cms>. A key must have been associated with the structure
 first.
 
+CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
+B<ri> in structure B<cms>. A key must have been associated with the structure
+first and the content encryption key must be available: for example by a
+previous call to CMS_RecipientInfo_decrypt().
+
 =head1 NOTES
 
 The main purpose of these functions is to enable an application to lookup
@@ -76,11 +82,18 @@ In typical usage and application will retrieve all CMS_RecipientInfo structures
 using CMS_get0_RecipientInfos() and check the type of each using
 CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
 can be ignored or its key identifier data retrieved using an appropriate
-function.  Then if the corresponding secret or private key can be obtained by
+function. Then if the corresponding secret or private key can be obtained by
 any appropriate means it can then associated with the structure and
 CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
 with a NULL key to decrypt the enveloped content.
 
+The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
+existing enveloped data structure. Typically an application will first decrypt
+an appropriate CMS_RecipientInfo structure to make the content encrypt key
+available, it will then add a new recipient using a function such as
+CMS_add1_recipient_cert() and finally encrypt the content encryption key
+using CMS_RecipientInfo_encrypt().
+
 =head1 RETURN VALUES
 
 CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
@@ -89,9 +102,10 @@ an error occurs.
 CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
 CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
 CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
+CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
 
 CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
-for a successul comparison and non zero otherwise.
+for a successful comparison and non zero otherwise.
 
 Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.