Debian Codegraph @

upstream/debian-unstable/man3/OSSL_DECODER_CTX_new_for_pkey.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_DECODER_CTX_NEW_FOR_PKEY 3SSL"
58 .TH OSSL_DECODER_CTX_NEW_FOR_PKEY 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_DECODER_CTX_new_for_pkey,
65 OSSL_DECODER_CTX_set_passphrase,
66 OSSL_DECODER_CTX_set_pem_password_cb,
67 OSSL_DECODER_CTX_set_passphrase_ui,
68 OSSL_DECODER_CTX_set_passphrase_cb
69 \&\- Decoder routines to decode EVP_PKEYs
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/decoder.h>
74 \&
75 \& OSSL_DECODER_CTX *
76 \& OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
77 \& const char *input_type,
78 \& const char *input_struct,
79 \& const char *keytype, int selection,
80 \& OSSL_LIB_CTX *libctx, const char *propquery);
81 \&
82 \& int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
83 \& const unsigned char *kstr,
84 \& size_t klen);
85 \& int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
86 \& pem_password_cb *cb,
87 \& void *cbarg);
88 \& int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
89 \& const UI_METHOD *ui_method,
90 \& void *ui_data);
91 \& int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
92 \& OSSL_PASSPHRASE_CALLBACK *cb,
93 \& void *cbarg);
94 .Ve
95 .SH DESCRIPTION
96 .IX Header "DESCRIPTION"
97 \&\fBOSSL_DECODER_CTX_new_for_pkey()\fR is a utility function that creates a
98 \&\fBOSSL_DECODER_CTX\fR, finds all applicable decoder implementations and sets
99 them up, so all the caller has to do next is call functions like
100 \&\fBOSSL_DECODER_from_bio\fR\|(3). The caller may use the optional \fIinput_type\fR,
101 \&\fIinput_struct\fR, \fIkeytype\fR and \fIselection\fR to specify what the input is
102 expected to contain. The \fIpkey\fR must reference an \fBEVP_PKEY *\fR variable
103 that will be set to the newly created \fBEVP_PKEY\fR on successful decoding.
104 The referenced variable must be initialized to NULL before calling the
105 function.
106 .PP
107 Internally \fBOSSL_DECODER_CTX_new_for_pkey()\fR searches for all available
108 \&\fBEVP_KEYMGMT\fR\|(3) implementations, and then builds a list of all potential
109 decoder implementations that may be able to process the encoded input into
110 data suitable for \fBEVP_PKEY\fRs. All these implementations are implicitly
111 fetched using \fIlibctx\fR and \fIpropquery\fR.
112 .PP
113 The search of decoder implementations can be limited with \fIinput_type\fR and
114 \&\fIinput_struct\fR which specifies a starting input type and input structure.
115 NULL is valid for both of them and signifies that the decoder implementations
116 will find out the input type on their own.
117 They are set with \fBOSSL_DECODER_CTX_set_input_type\fR\|(3) and
118 \&\fBOSSL_DECODER_CTX_set_input_structure\fR\|(3).
119 See "Input Types" and "Input Structures" below for further information.
120 .PP
121 The search of decoder implementations can also be limited with \fIkeytype\fR
122 and \fIselection\fR, which specifies the expected resulting keytype and contents.
123 NULL and zero are valid and signify that the decoder implementations will
124 find out the keytype and key contents on their own from the input they get.
125 .PP
126 If no suitable decoder implementation is found,
127 \&\fBOSSL_DECODER_CTX_new_for_pkey()\fR still creates a \fBOSSL_DECODER_CTX\fR, but
128 with no associated decoder (\fBOSSL_DECODER_CTX_get_num_decoders\fR\|(3) returns
129 zero). This helps the caller to distinguish between an error when creating
130 the \fBOSSL_ENCODER_CTX\fR and missing encoder implementation, and allows it to
131 act accordingly.
132 .PP
133 Note that \fBOSSL_DECODER_CTX_new_for_pkey()\fR finalises the OSSL_DECODER_CTX;
134 after that the OSSL_DECODER_CTX_set_* and OSSL_DECODER_CTX_add_* functions
135 described in \fBOSSL_DECODER_CTX\fR\|(3) shouldn't be called.
136 .PP
137 \&\fBOSSL_DECODER_CTX_set_passphrase()\fR gives the implementation a pass phrase to
138 use when decrypting the encoded private key. Alternatively, a pass phrase
139 callback may be specified with the following functions.
140 .PP
141 \&\fBOSSL_DECODER_CTX_set_pem_password_cb()\fR, \fBOSSL_DECODER_CTX_set_passphrase_ui()\fR
142 and \fBOSSL_DECODER_CTX_set_passphrase_cb()\fR set up a callback method that the
143 implementation can use to prompt for a pass phrase, giving the caller the
144 choice of preferred pass phrase callback form. These are called indirectly,
145 through an internal \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function.
146 .PP
147 The internal \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function caches the pass phrase, to
148 be reused in all decodings that are performed in the same decoding run (for
149 example, within one \fBOSSL_DECODER_from_bio\fR\|(3) call).
150 .SS "Input Types"
151 .IX Subsection "Input Types"
152 Available input types depend on the implementations that available providers
153 offer, and provider documentation should have the details.
154 .PP
155 Among the known input types that OpenSSL decoder implementations offer
156 for \fBEVP_PKEY\fRs are \f(CW\*(C`DER\*(C'\fR, \f(CW\*(C`PEM\*(C'\fR, \f(CW\*(C`MSBLOB\*(C'\fR and \f(CW\*(C`PVK\*(C'\fR.
157 See \fBopenssl\-glossary\fR\|(7) for further information on what these input
158 types mean.
159 .SS "Input Structures"
160 .IX Subsection "Input Structures"
161 Available input structures depend on the implementations that available
162 providers offer, and provider documentation should have the details.
163 .PP
164 Among the known input structures that OpenSSL decoder implementations
165 offer for \fBEVP_PKEY\fRs are \f(CW\*(C`pkcs8\*(C'\fR and \f(CW\*(C`SubjectPublicKeyInfo\*(C'\fR.
166 .PP
167 OpenSSL decoder implementations also support the input structure
168 \&\f(CW\*(C`type\-specific\*(C'\fR. This is the structure used for keys encoded
169 according to key type specific specifications. For example, RSA keys
170 encoded according to PKCS#1.
171 .SS Selections
172 .IX Subsection "Selections"
173 \&\fIselection\fR can be any one of the values described in
174 "Selections" in \fBEVP_PKEY_fromdata\fR\|(3).
175 Additionally \fIselection\fR can also be set to \fB0\fR to indicate that the code will
176 auto detect the selection.
177 .SH "RETURN VALUES"
178 .IX Header "RETURN VALUES"
179 \&\fBOSSL_DECODER_CTX_new_for_pkey()\fR returns a pointer to a
180 \&\fBOSSL_DECODER_CTX\fR, or NULL if it couldn't be created.
181 .PP
182 \&\fBOSSL_DECODER_CTX_set_passphrase()\fR, \fBOSSL_DECODER_CTX_set_pem_password_cb()\fR,
183 \&\fBOSSL_DECODER_CTX_set_passphrase_ui()\fR and
184 \&\fBOSSL_DECODER_CTX_set_passphrase_cb()\fR all return 1 on success, or 0 on
185 failure.
186 .SH "SEE ALSO"
187 .IX Header "SEE ALSO"
188 \&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3), \fBOSSL_DECODER_CTX\fR\|(3)
189 .SH HISTORY
190 .IX Header "HISTORY"
191 The functions described here were added in OpenSSL 3.0.
192 .SH COPYRIGHT
193 .IX Header "COPYRIGHT"
194 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
195 .PP
196 Licensed under the Apache License 2.0 (the "License"). You may not use
197 this file except in compliance with the License. You can obtain a copy
198 in the file LICENSE in the source distribution or at
199 <https://www.openssl.org/source/license.html>.