2
0

CMS_get0_RecipientInfos.pod 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
  1. =pod
  2. =head1 NAME
  3. 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
  4. =head1 SYNOPSIS
  5. #include <openssl/cms.h>
  6. STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
  7. int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
  8. int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
  9. int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
  10. int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
  11. int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
  12. int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
  13. int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
  14. int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
  15. =head1 DESCRIPTION
  16. The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
  17. structures associated with a CMS EnvelopedData structure.
  18. CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
  19. It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
  20. CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
  21. CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
  22. identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
  23. must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
  24. B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
  25. CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
  26. CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
  27. It returns zero if the comparison is successful and non zero if not.
  28. CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
  29. the CMS_RecipientInfo structure B<ri>, which must be of type
  30. CMS_RECIPINFO_TRANS.
  31. CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
  32. CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
  33. of the remaining parameters can be NULL if the application is not interested in
  34. the value of a field. Where a field is optional and absent NULL will be written
  35. to the corresponding parameter. The keyEncryptionAlgorithm field is written to
  36. B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
  37. present is written to B<pdate>, if the B<other> field is present the components
  38. B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
  39. B<pothertype>.
  40. CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
  41. parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
  42. which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
  43. successful and non zero if not.
  44. CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
  45. B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
  46. CMS_RECIPINFO_KEK.
  47. CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
  48. B<ri> in structure B<cms>. A key must have been associated with the structure
  49. first.
  50. =head1 NOTES
  51. The main purpose of these functions is to enable an application to lookup
  52. recipient keys using any appropriate technique when the simpler method
  53. of CMS_decrypt() is not appropriate.
  54. In typical usage and application will retrieve all CMS_RecipientInfo structures
  55. using CMS_get0_RecipientInfos() and check the type of each using
  56. CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
  57. can be ignored or its key identifier data retrieved using an appropriate
  58. function. Then if the corresponding secret or private key can be obtained by
  59. any appropriate means it can then associated with the structure and
  60. CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
  61. with a NULL key to decrypt the enveloped content.
  62. =head1 RETURN VALUES
  63. CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
  64. an error occurs.
  65. CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
  66. CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
  67. CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
  68. CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
  69. for a successful comparison and non zero otherwise.
  70. Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
  71. =head1 SEE ALSO
  72. L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
  73. =head1 HISTORY
  74. These functions were first was added to OpenSSL 0.9.8
  75. =cut