Debian Codegraph @

upstream/debian-unstable/man3/CMS_add1_recipient_cert.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CMS_ADD1_RECIPIENT_CERT 3SSL"
58 .TH CMS_ADD1_RECIPIENT_CERT 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key \- add recipients to a CMS enveloped data structure
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/cms.h>
69 \&
70 \& CMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,
71 \& EVP_PKEY *originatorPrivKey,
72 \& X509 *originator, unsigned int flags);
73 \&
74 \& CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
75 \& X509 *recip, unsigned int flags);
76 \&
77 \& CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
78 \& unsigned char *key, size_t keylen,
79 \& unsigned char *id, size_t idlen,
80 \& ASN1_GENERALIZEDTIME *date,
81 \& ASN1_OBJECT *otherTypeId,
82 \& ASN1_TYPE *otherType);
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 \&\fBCMS_add1_recipient()\fR adds recipient \fBrecip\fR and provides the originator pkey
87 \&\fBoriginatorPrivKey\fR and originator certificate \fBoriginator\fR to CMS_ContentInfo.
88 The originator-related fields are relevant only in case when the keyAgreement
89 method of providing of the shared key is in use.
90 .PP
91 \&\fBCMS_add1_recipient_cert()\fR adds recipient \fBrecip\fR to CMS_ContentInfo enveloped
92 data structure \fBcms\fR as a KeyTransRecipientInfo or KEMRecipientInfo structure,
93 or as a KeyAgreeRecipientInfo structure with an ephemeral key.
94 .PP
95 \&\fBCMS_add0_recipient_key()\fR adds symmetric key \fBkey\fR of length \fBkeylen\fR using
96 wrapping algorithm \fBnid\fR, identifier \fBid\fR of length \fBidlen\fR and optional
97 values \fBdate\fR, \fBotherTypeId\fR and \fBotherType\fR to CMS_ContentInfo enveloped
98 data structure \fBcms\fR as a KEKRecipientInfo structure.
99 .PP
100 The CMS_ContentInfo structure should be obtained from an initial call to
101 \&\fBCMS_encrypt()\fR with the flag \fBCMS_PARTIAL\fR set.
102 .SH NOTES
103 .IX Header "NOTES"
104 The main purpose of this function is to provide finer control over a CMS
105 enveloped data structure where the simpler \fBCMS_encrypt()\fR function defaults are
106 not appropriate. For example if one or more KEKRecipientInfo structures
107 need to be added. New attributes can also be added using the returned
108 CMS_RecipientInfo structure and the CMS attribute utility functions.
109 .PP
110 OpenSSL will by default identify recipient certificates using issuer name
111 and serial number. If \fBCMS_USE_KEYID\fR is set it will use the subject key
112 identifier value instead. An error occurs if all recipient certificates do not
113 have a subject key identifier extension.
114 .PP
115 Currently only AES based key wrapping algorithms are supported for \fBnid\fR,
116 specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
117 If \fBnid\fR is set to \fBNID_undef\fR then an AES wrap algorithm will be used
118 consistent with \fBkeylen\fR.
119 .SH "RETURN VALUES"
120 .IX Header "RETURN VALUES"
121 \&\fBCMS_add1_recipient_cert()\fR and \fBCMS_add0_recipient_key()\fR return an internal
122 pointer to the CMS_RecipientInfo structure just added or NULL if an error
123 occurs.
124 .SH "SEE ALSO"
125 .IX Header "SEE ALSO"
126 \&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3),
127 \&\fBCMS_final\fR\|(3),
128 .SH HISTORY
129 .IX Header "HISTORY"
130 \&\fBCMS_add1_recipient_cert\fR and \fBCMS_add0_recipient_key\fR were added in
131 OpenSSL 3.0.
132 .SH COPYRIGHT
133 .IX Header "COPYRIGHT"
134 Copyright 2008\-2025 The OpenSSL Project Authors. All Rights Reserved.
135 .PP
136 Licensed under the Apache License 2.0 (the "License"). You may not use
137 this file except in compliance with the License. You can obtain a copy
138 in the file LICENSE in the source distribution or at
139 <https://www.openssl.org/source/license.html>.