CMS_get0_RecipientInfos.pod@ 97673

最後變更在這個檔案從97673是 94082,由 vboxsync 提交於 3 年前
libs/openssl-3.0.1: started applying and adjusting our OpenSSL changes to 3.0.1. bugref:10128
檔案大小: 7.0 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

source: vbox/trunk/src/libs/openssl-3.0.7/doc/man3/CMS_get0_RecipientInfos.pod@ 97673

以其他格式下載: