1.Dd $Mdocdate: November 11 2015 $ 2.Dt CMS_GET0_RECIPIENTINFOS 3 3.Os 4.Sh NAME 5.Nm CMS_get0_RecipientInfos , 6.Nm CMS_RecipientInfo_type , 7.Nm CMS_RecipientInfo_ktri_get0_signer_id , 8.Nm CMS_RecipientInfo_ktri_cert_cmp , 9.Nm CMS_RecipientInfo_set0_pkey , 10.Nm CMS_RecipientInfo_kekri_get0_id , 11.Nm CMS_RecipientInfo_kekri_id_cmp , 12.Nm CMS_RecipientInfo_set0_key , 13.Nm CMS_RecipientInfo_decrypt , 14.Nm CMS_RecipientInfo_encrypt 15.Nd CMS envelopedData RecipientInfo routines 16.Sh SYNOPSIS 17.In openssl/cms.h 18.Ft STACK_OF(CMS_RecipientInfo) * 19.Fo CMS_get0_RecipientInfos 20.Fa "CMS_ContentInfo *cms" 21.Fc 22.Ft int 23.Fo CMS_RecipientInfo_type 24.Fa "CMS_RecipientInfo *ri" 25.Fc 26.Ft int 27.Fo CMS_RecipientInfo_ktri_get0_signer_id 28.Fa "CMS_RecipientInfo *ri" 29.Fa "ASN1_OCTET_STRING **keyid" 30.Fa "X509_NAME **issuer" 31.Fa "ASN1_INTEGER **sno" 32.Fc 33.Ft int 34.Fo CMS_RecipientInfo_ktri_cert_cmp 35.Fa "CMS_RecipientInfo *ri" 36.Fa "X509 *cert" 37.Fc 38.Ft int 39.Fo CMS_RecipientInfo_set0_pkey 40.Fa "CMS_RecipientInfo *ri" 41.Fa "EVP_PKEY *pkey" 42.Fc 43.Ft int 44.Fo CMS_RecipientInfo_kekri_get0_id 45.Fa "CMS_RecipientInfo *ri" 46.Fa "X509_ALGOR **palg" 47.Fa "ASN1_OCTET_STRING **pid" 48.Fa "ASN1_GENERALIZEDTIME **pdate" 49.Fa "ASN1_OBJECT **potherid" 50.Fa "ASN1_TYPE **pothertype" 51.Fc 52.Ft int 53.Fo CMS_RecipientInfo_kekri_id_cmp 54.Fa "CMS_RecipientInfo *ri" 55.Fa "const unsigned char *id" 56.Fa "size_t idlen" 57.Fc 58.Ft int 59.Fo CMS_RecipientInfo_set0_key 60.Fa "CMS_RecipientInfo *ri" 61.Fa "unsigned char *key" 62.Fa "size_t keylen" 63.Fc 64.Ft int 65.Fo CMS_RecipientInfo_decrypt 66.Fa "CMS_ContentInfo *cms" 67.Fa "CMS_RecipientInfo *ri" 68.Fc 69.Sh DESCRIPTION 70The function 71.Fn CMS_get0_RecipientInfos 72returns all the 73.Vt CMS_RecipientInfo 74structures associated with a CMS EnvelopedData structure. 75.Pp 76.Fn CMS_RecipientInfo_type 77returns the type of the 78.Vt CMS_RecipientInfo 79structure 80.Fa ri . 81It will currently return 82.Dv CMS_RECIPINFO_TRANS , 83.Dv CMS_RECIPINFO_AGREE , 84.Dv CMS_RECIPINFO_KEK , 85.Dv CMS_RECIPINFO_PASS , 86or 87.Dv CMS_RECIPINFO_OTHER . 88.Pp 89.Fn CMS_RecipientInfo_ktri_get0_signer_id 90retrieves the certificate recipient identifier associated with a 91specific 92.Vt CMS_RecipientInfo 93structure 94.Fa ri , 95which must be of type 96.Dv CMS_RECIPINFO_TRANS . 97Either the keyidentifier will be set in 98.Fa keyid 99or 100.Em both 101issuer name and serial number in 102.Fa issuer 103and 104.Fa sno . 105.Pp 106.Fn CMS_RecipientInfo_ktri_cert_cmp 107compares the certificate 108.Fa cert 109against the 110.Vt CMS_RecipientInfo 111structure 112.Fa ri , 113which must be of type 114.Dv CMS_RECIPINFO_TRANS . 115It returns zero if the 116comparison is successful and non zero if not. 117.Pp 118.Fn CMS_RecipientInfo_set0_pkey 119associates the private key 120.Fa pkey 121with the 122.Vt CMS_RecipientInfo 123structure 124.Fa ri , 125which must be of type 126.Dv CMS_RECIPINFO_TRANS . 127.Pp 128.Fn CMS_RecipientInfo_kekri_get0_id 129retrieves the key information from the 130.Vt CMS_RecipientInfo 131structure 132.Fa ri 133which must be of type 134.Dv CMS_RECIPINFO_KEK . 135Any of the remaining parameters can be 136.Dv NULL 137if the application is not interested in the value of a field. 138Where a field is optional and absent, 139.Dv NULL 140will be written to the corresponding parameter. 141The 142.Sy keyEncryptionAlgorithm 143field is written to 144.Fa palg , 145the 146.Sy keyIdentifier 147field is written to 148.Fa pid , 149the 150.Sy date 151field if present is written to 152.Fa pdate , 153if the 154.Sy other 155field is present the components 156.Sy keyAttrId 157and 158.Sy keyAttr 159are written to the parameters 160.Fa potherid 161and 162.Fa pothertype . 163.Pp 164.Fn CMS_RecipientInfo_kekri_id_cmp 165compares the ID in the 166.Fa id 167and 168.Fa idlen 169parameters against the 170.Sy keyIdentifier 171.Vt CMS_RecipientInfo 172structure 173.Fa ri , 174which must be of type 175.Dv CMS_RECIPINFO_KEK . 176It returns zero if the comparison is successful and non zero if not. 177.Pp 178.Fn CMS_RecipientInfo_set0_key 179associates the symmetric key 180.Fa key 181of length 182.Fa keylen 183with the 184.Vt CMS_RecipientInfo 185structure 186.Fa ri , 187which must be of type 188.Dv CMS_RECIPINFO_KEK . 189.Pp 190.Fn CMS_RecipientInfo_decrypt 191attempts to decrypt the 192.Vt CMS_RecipientInfo 193structure 194.Fa ri 195in structure 196.Fa cms . 197A key must have been associated with the structure first. 198.Sh NOTES 199The main purpose of these functions is to enable an application to 200lookup recipient keys using any appropriate technique when the simpler 201method of 202.Xr CMS_decrypt 3 203is not appropriate. 204.Pp 205In typical usage, an application will retrieve all 206.Vt CMS_RecipientInfo 207structures using 208.Fn CMS_get0_RecipientInfos 209and check the type of each using 210.Fn CMS_RecipientInfo_type . 211Depending on the type, the 212.Vt CMS_RecipientInfo 213structure can be ignored or its key identifier data retrieved using 214an appropriate function. 215Then if the corresponding secret or private key can be obtained by any 216appropriate means it can then associated with the structure and 217.Xr CMS_RecpientInfo_decrypt 3 218called. 219If successful, 220.Xr CMS_decrypt 3 221can be called with a 222.Dv NULL 223key to decrypt the enveloped content. 224.Sh RETURN VALUES 225.Fn CMS_get0_RecipientInfos 226returns all 227.Vt CMS_RecipientInfo 228structures, or 229.Dv NULL 230if an error occurs. 231.Pp 232.Fn CMS_RecipientInfo_ktri_get0_signer_id , 233.Fn CMS_RecipientInfo_set0_pkey , 234.Fn CMS_RecipientInfo_kekri_get0_id , 235.Fn CMS_RecipientInfo_set0_key , 236and 237.Fn CMS_RecipientInfo_decrypt 238return 1 for success or 0 if an error occurs. 239.Pp 240.Fn CMS_RecipientInfo_ktri_cert_cmp 241and 242.Fn CMS_RecipientInfo_kekri_id_cmp 243return 0 for a successful comparison and non zero otherwise. 244.Pp 245Any error can be obtained from 246.Xr ERR_get_error 3 . 247.Sh SEE ALSO 248.Xr CMS_decrypt 3 , 249.Xr ERR_get_error 3 250.Sh HISTORY 251These functions were first was added to OpenSSL 0.9.8. 252