[thirdparty/openssl.git] / doc / man3 / CMS_get0_RecipientInfos.pod

=pod

=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_RecipientInfo_encrypt
- CMS envelopedData RecipientInfo routines

=head1 SYNOPSIS

 #include <openssl/cms.h>

 STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
 int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);

 int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
                                           ASN1_OCTET_STRING **keyid,
                                           X509_NAME **issuer,
                                           ASN1_INTEGER **sno);
 int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
 int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);

 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);
 int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
                                    const unsigned char *id, size_t idlen);
 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.

CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.

CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
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 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.

CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_TRANS.

CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK.  Any
of the remaining parameters can be NULL if the application is not interested in
the value of a field. Where a field is optional and absent NULL will be written
to the corresponding parameter. The keyEncryptionAlgorithm field is written to
B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
present is written to B<pdate>, if the B<other> field is present the components
B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
B<pothertype>.

CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
which must be of type CMS_RECIPINFO_KEK.  It returns zero if the comparison is
successful and non zero if not.

CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_KEK.

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
recipient keys using any appropriate technique when the simpler method
of CMS_decrypt() is not appropriate.

In typical usage and application will retrieve all CMS_RecipientInfo structures
using CMS_get0_RecipientInfos() and check the type of each using
CMS_RecipientInfo_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
any appropriate means it can then associated with the structure and
CMS_RecipientInfo_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
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 successful comparison and non zero otherwise.

Any error can be obtained from L<ERR_get_error(3)>.

=head1 SEE ALSO

L<ERR_get_error(3)>, L<CMS_decrypt(3)>

=head1 COPYRIGHT

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
847e551f DSH	1	=pod
	2
	3	=head1 NAME
	4
c952780c RS	5	CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
	6	CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
	7	CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
	8	CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
	9	CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
	10	- CMS envelopedData RecipientInfo routines
847e551f DSH	11
	12	=head1 SYNOPSIS
	13
	14	#include <openssl/cms.h>
	15
	16	STACK_OF(CMS_RecipientInfo) CMS_get0_RecipientInfos(CMS_ContentInfo cms);
	17	int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
	18
e9b77246 BB	19	int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
	20	ASN1_OCTET_STRING **keyid,
	21	X509_NAME **issuer,
	22	ASN1_INTEGER **sno);
847e551f DSH	23	int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo ri, X509 cert);
	24	int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo ri, EVP_PKEY pkey);
	25
e9b77246 BB	26	int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo ri, X509_ALGOR *palg,
	27	ASN1_OCTET_STRING **pid,
	28	ASN1_GENERALIZEDTIME **pdate,
	29	ASN1_OBJECT **potherid,
	30	ASN1_TYPE **pothertype);
	31	int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
	32	const unsigned char *id, size_t idlen);
	33	int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
	34	unsigned char *key, size_t keylen);
847e551f DSH	35
847e551f DSH	36	int CMS_RecipientInfo_decrypt(CMS_ContentInfo cms, CMS_RecipientInfo ri);
e1f1d28f	37	int CMS_RecipientInfo_encrypt(CMS_ContentInfo cms, CMS_RecipientInfo ri);
847e551f DSH	38
	39	=head1 DESCRIPTION
	40
	41	The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
38d3a738	42	structures associated with a CMS EnvelopedData structure.
847e551f DSH	43
	44	CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
	45	It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
	46	CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
	47
	48	CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
	49	identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
	50	must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
1bc74519	51	B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
847e551f	52
c420fab5	53	CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
847e551f DSH	54	CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
	55	It returns zero if the comparison is successful and non zero if not.
	56
	57	CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
	58	the CMS_RecipientInfo structure B<ri>, which must be of type
	59	CMS_RECIPINFO_TRANS.
	60
	61	CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
	62	CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
	63	of the remaining parameters can be NULL if the application is not interested in
	64	the value of a field. Where a field is optional and absent NULL will be written
	65	to the corresponding parameter. The keyEncryptionAlgorithm field is written to
	66	B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
	67	present is written to B<pdate>, if the B<other> field is present the components
	68	B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
	69	B<pothertype>.
	70
	71	CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
	72	parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
	73	which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
	74	successful and non zero if not.
	75
	76	CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
	77	B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
	78	CMS_RECIPINFO_KEK.
	79
	80	CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
	81	B<ri> in structure B<cms>. A key must have been associated with the structure
	82	first.
	83
e1f1d28f DSH	84	CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
	85	B<ri> in structure B<cms>. A key must have been associated with the structure
	86	first and the content encryption key must be available: for example by a
	87	previous call to CMS_RecipientInfo_decrypt().
	88
847e551f DSH	89	=head1 NOTES
	90
	91	The main purpose of these functions is to enable an application to lookup
	92	recipient keys using any appropriate technique when the simpler method
	93	of CMS_decrypt() is not appropriate.
	94
	95	In typical usage and application will retrieve all CMS_RecipientInfo structures
	96	using CMS_get0_RecipientInfos() and check the type of each using
df578aa0	97	CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure
847e551f	98	can be ignored or its key identifier data retrieved using an appropriate
38d3a738	99	function. Then if the corresponding secret or private key can be obtained by
847e551f	100	any appropriate means it can then associated with the structure and
df578aa0	101	CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called
847e551f DSH	102	with a NULL key to decrypt the enveloped content.
847e551f DSH	103
e1f1d28f DSH	104	The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
	105	existing enveloped data structure. Typically an application will first decrypt
	106	an appropriate CMS_RecipientInfo structure to make the content encrypt key
	107	available, it will then add a new recipient using a function such as
	108	CMS_add1_recipient_cert() and finally encrypt the content encryption key
	109	using CMS_RecipientInfo_encrypt().
	110
847e551f DSH	111	=head1 RETURN VALUES
	112
	113	CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
	114	an error occurs.
	115
	116	CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
	117	CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
	118	CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
e1f1d28f	119	CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
847e551f DSH	120
847e551f DSH	121	CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
c420fab5	122	for a successful comparison and non zero otherwise.
847e551f	123
9b86974e	124	Any error can be obtained from L<ERR_get_error(3)>.
847e551f DSH	125
	126	=head1 SEE ALSO
	127
9b86974e	128	L<ERR_get_error(3)>, L<CMS_decrypt(3)>
847e551f	129
e2f92610 RS	130	=head1 COPYRIGHT
	131
	132	Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
	133
4746f25a	134	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	135	this file except in compliance with the License. You can obtain a copy
	136	in the file LICENSE in the source distribution or at
	137	L<https://www.openssl.org/source/license.html>.
	138
	139	=cut