Debian Codegraph @

upstream/debian-unstable/man3/OSSL_CRMF_MSG_get0_tmpl.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 "OSSL_CRMF_MSG_GET0_TMPL 3SSL"
58 .TH OSSL_CRMF_MSG_GET0_TMPL 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 OSSL_CRMF_MSG_get0_tmpl,
65 OSSL_CRMF_CERTTEMPLATE_get0_publicKey,
66 OSSL_CRMF_CERTTEMPLATE_get0_subject,
67 OSSL_CRMF_CERTTEMPLATE_get0_issuer,
68 OSSL_CRMF_CERTTEMPLATE_get0_serialNumber,
69 OSSL_CRMF_CERTTEMPLATE_get0_extensions,
70 OSSL_CRMF_CERTID_get0_serialNumber,
71 OSSL_CRMF_CERTID_get0_issuer,
72 OSSL_CRMF_ENCRYPTEDKEY_get1_encCert,
73 OSSL_CRMF_ENCRYPTEDKEY_get1_pkey,
74 OSSL_CRMF_ENCRYPTEDKEY_init_envdata,
75 OSSL_CRMF_ENCRYPTEDVALUE_decrypt,
76 OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert,
77 OSSL_CRMF_MSG_get_certReqId,
78 OSSL_CRMF_MSG_centralkeygen_requested
79 \&\- functions reading from CRMF CertReqMsg structures
80 .SH SYNOPSIS
81 .IX Header "SYNOPSIS"
82 .Vb 1
83 \& #include <openssl/crmf.h>
84 \&
85 \& OSSL_CRMF_CERTTEMPLATE *OSSL_CRMF_MSG_get0_tmpl(const OSSL_CRMF_MSG *crm);
86 \& X509_PUBKEY
87 \& *OSSL_CRMF_CERTTEMPLATE_get0_publicKey(const OSSL_CRMF_CERTTEMPLATE *tmpl);
88 \& const X509_NAME
89 \& *OSSL_CRMF_CERTTEMPLATE_get0_subject(const OSSL_CRMF_CERTTEMPLATE *tmpl);
90 \& const X509_NAME
91 \& *OSSL_CRMF_CERTTEMPLATE_get0_issuer(const OSSL_CRMF_CERTTEMPLATE *tmpl);
92 \& const ASN1_INTEGER
93 \& *OSSL_CRMF_CERTTEMPLATE_get0_serialNumber(const OSSL_CRMF_CERTTEMPLATE *tmpl);
94 \& X509_EXTENSIONS
95 \& *OSSL_CRMF_CERTTEMPLATE_get0_extensions(const OSSL_CRMF_CERTTEMPLATE *tmpl);
96 \&
97 \& const ASN1_INTEGER
98 \& *OSSL_CRMF_CERTID_get0_serialNumber(const OSSL_CRMF_CERTID *cid);
99 \& const X509_NAME *OSSL_CRMF_CERTID_get0_issuer(const OSSL_CRMF_CERTID *cid);
100 \&
101 \& X509 *OSSL_CRMF_ENCRYPTEDKEY_get1_encCert(const OSSL_CRMF_ENCRYPTEDKEY *ecert,
102 \& OSSL_LIB_CTX *libctx, const char *propq,
103 \& EVP_PKEY *pkey, unsigned int flags);
104 \& EVP_PKEY
105 \& *OSSL_CRMF_ENCRYPTEDKEY_get1_pkey(OSSL_CRMF_ENCRYPTEDKEY *encryptedKey,
106 \& X509_STORE *ts, STACK_OF(X509) *extra,
107 \& EVP_PKEY *pkey, X509 *cert,
108 \& ASN1_OCTET_STRING *secret,
109 \& OSSL_LIB_CTX *libctx, const char *propq);
110 \& OSSL_CRMF_ENCRYPTEDKEY
111 \& *OSSL_CRMF_ENCRYPTEDKEY_init_envdata(CMS_EnvelopedData *envdata);
112 \&
113 \& unsigned char
114 \& *OSSL_CRMF_ENCRYPTEDVALUE_decrypt(const OSSL_CRMF_ENCRYPTEDVALUE *enc,
115 \& OSSL_LIB_CTX *libctx, const char *propq,
116 \& EVP_PKEY *pkey, int *outlen);
117 \& X509
118 \& *OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(const OSSL_CRMF_ENCRYPTEDVALUE *ecert,
119 \& OSSL_LIB_CTX *libctx, const char *propq,
120 \& EVP_PKEY *pkey);
121 \&
122 \& int OSSL_CRMF_MSG_get_certReqId(const OSSL_CRMF_MSG *crm);
123 \& int OSSL_CRMF_MSG_centralkeygen_requested(const OSSL_CRMF_MSG *crm,
124 \& const X509_REQ *p10cr);
125 .Ve
126 .SH DESCRIPTION
127 .IX Header "DESCRIPTION"
128 \&\fBOSSL_CRMF_MSG_get0_tmpl()\fR retrieves the certificate template of \fIcrm\fR.
129 .PP
130 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_publicKey()\fR retrieves the public key of the
131 given certificate template \fItmpl\fR.
132 .PP
133 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_subject()\fR retrieves the subject name of the
134 given certificate template \fItmpl\fR.
135 .PP
136 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_issuer()\fR retrieves the issuer name of the
137 given certificate template \fItmpl\fR.
138 .PP
139 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_serialNumber()\fR retrieves the serialNumber of the
140 given certificate template \fItmpl\fR.
141 .PP
142 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_extensions()\fR retrieves the X.509 extensions
143 of the given certificate template \fItmpl\fR, or NULL if not present.
144 .PP
145 OSSL_CRMF_CERTID_get0_serialNumber retrieves the serialNumber
146 of the given CertId \fIcid\fR.
147 .PP
148 OSSL_CRMF_CERTID_get0_issuer retrieves the issuer name
149 of the given CertId \fIcid\fR, which must be of ASN.1 type GEN_DIRNAME.
150 .PP
151 \&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_encCert()\fR decrypts the certificate in the given
152 encryptedKey \fIecert\fR, using the private key \fIpkey\fR, library context
153 \&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)).
154 This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2.
155 The function returns the decrypted certificate as a copy, leaving its ownership
156 with the caller, who is responsible for freeing it.
157 .PP
158 \&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_pkey()\fR decrypts the private key in \fIencryptedKey\fR.
159 If \fIencryptedKey\fR is not of type \fBOSSL_CRMF_ENCRYPTEDKEY_ENVELOPEDDATA\fR,
160 decryption uses the private key \fIpkey\fR.
161 The library context \fIlibctx\fR and property query \fIpropq\fR are taken into account as usual.
162 The rest of this paragraph is relevant only if CMS support not disabled for the OpenSSL build
163 and \fIencryptedKey\fR is of type case \fBOSSL_CRMF_ENCRYPTEDKEY_ENVELOPEDDATA\fR.
164 Decryption uses the \fIsecret\fR parameter if not NULL;
165 otherwise uses the private key <pkey> and the certificate \fIcert\fR
166 related to \fIpkey\fR, where \fIcert\fR is recommended to be given if available.
167 On success, the function verifies the decrypted data as signed data,
168 using the trust store \fIts\fR and any untrusted certificates in \fIextra\fR.
169 Doing so, it checks for the purpose "CMP Key Generation Authority" (cmKGA).
170 .PP
171 \&\fBOSSL_CRMF_ENCRYPTEDKEY_init_envdata()\fR returns \fIOSSL_CRMF_ENCRYPTEDKEY\fR, initialized with
172 the enveloped data \fIenvdata\fR.
173 .PP
174 \&\fBOSSL_CRMF_ENCRYPTEDVALUE_decrypt()\fR decrypts the encrypted value in the given
175 encryptedValue \fIenc\fR, using the private key \fIpkey\fR, library context
176 \&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)).
177 .PP
178 \&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert()\fR decrypts the certificate in the given
179 encryptedValue \fIecert\fR, using the private key \fIpkey\fR, library context
180 \&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)).
181 This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2.
182 The function returns the decrypted certificate as a copy, leaving its ownership
183 with the caller, who is responsible for freeing it.
184 .PP
185 \&\fBOSSL_CRMF_MSG_get_certReqId()\fR retrieves the certReqId of \fIcrm\fR.
186 .PP
187 \&\fBOSSL_CRMF_MSG_centralkeygen_requested()\fR returns 1 if central key generation
188 is requested i.e., the public key in the certificate request (\fIcrm\fR is taken if it is non-NULL,
189 otherwise \fIp10cr\fR) is NULL or has an empty key value (with length zero).
190 In case \fIcrm\fR is non-NULL, this is checked for consistency with its \fBpopo\fR field
191 (must be NULL if and only if central key generation is requested).
192 Otherwise it returns 0, and on error a negative value.
193 .SH "RETURN VALUES"
194 .IX Header "RETURN VALUES"
195 \&\fBOSSL_CRMF_MSG_get_certReqId()\fR returns the certificate request ID as a
196 nonnegative integer or \-1 on error.
197 .PP
198 \&\fBOSSL_CRMF_MSG_centralkeygen_requested()\fR returns 1 if central key generation
199 is requested, 0 if it is not requested, and a negative value on error.
200 .PP
201 All other functions return a pointer with the intended result or NULL on error.
202 .SH "SEE ALSO"
203 .IX Header "SEE ALSO"
204 RFC 4211
205 .SH HISTORY
206 .IX Header "HISTORY"
207 The OpenSSL CRMF support was added in OpenSSL 3.0.
208 .PP
209 \&\fBOSSL_CRMF_CERTTEMPLATE_get0_publicKey()\fR was added in OpenSSL 3.2.
210 .PP
211 \&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_encCert()\fR, \fBOSSL_CRMF_ENCRYPTEDKEY_get1_pkey()\fR,
212 \&\fBOSSL_CRMF_ENCRYPTEDKEY_init_envdata()\fR, \fBOSSL_CRMF_ENCRYPTEDVALUE_decrypt()\fR
213 and \fBOSSL_CRMF_MSG_centralkeygen_requested()\fR were added in OpenSSL 3.5.
214 .SH COPYRIGHT
215 .IX Header "COPYRIGHT"
216 Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved.
217 .PP
218 Licensed under the Apache License 2.0 (the "License"). You may not use
219 this file except in compliance with the License. You can obtain a copy
220 in the file LICENSE in the source distribution or at
221 <https://www.openssl.org/source/license.html>.