1=pod
2
3=head1 NAME
4
5OSSL_DECODER_CTX_new_for_pkey,
6OSSL_DECODER_CTX_set_passphrase,
7OSSL_DECODER_CTX_set_pem_password_cb,
8OSSL_DECODER_CTX_set_passphrase_ui,
9OSSL_DECODER_CTX_set_passphrase_cb
10- Decoder routines to decode EVP_PKEYs
11
12=head1 SYNOPSIS
13
14 #include <openssl/decoder.h>
15
16 OSSL_DECODER_CTX *
17 OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
18                               const char *input_type,
19                               const char *input_struct,
20                               const char *keytype, int selection,
21                               OSSL_LIB_CTX *libctx, const char *propquery);
22
23 int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
24                                     const unsigned char *kstr,
25                                     size_t klen);
26 int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
27                                          pem_password_cb *cb,
28                                          void *cbarg);
29 int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
30                                        const UI_METHOD *ui_method,
31                                        void *ui_data);
32 int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
33                                        OSSL_PASSPHRASE_CALLBACK *cb,
34                                        void *cbarg);
35
36=head1 DESCRIPTION
37
38OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
39B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
40them up, so all the caller has to do next is call functions like
41L<OSSL_DECODER_from_bio(3)>.  The caller may use the optional I<input_type>,
42I<input_struct>, I<keytype> and I<selection> to specify what the input is
43expected to contain.  The I<pkey> must reference an B<EVP_PKEY *> variable
44that will be set to the newly created B<EVP_PKEY> on successful decoding.
45The referenced variable must be initialized to NULL before calling the
46function.
47
48Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available
49L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
50decoder implementations that may be able to process the encoded input into
51data suitable for B<EVP_PKEY>s.  All these implementations are implicitly
52fetched using I<libctx> and I<propquery>.
53
54The search of decoder implementations can be limited with I<input_type> and
55I<input_struct> which specifies a starting input type and input structure.
56NULL is valid for both of them and signifies that the decoder implementations
57will find out the input type on their own.
58They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and
59L<OSSL_DECODER_CTX_set_input_structure(3)>.
60See L</Input Types> and L</Input Structures> below for further information.
61
62The search of decoder implementations can also be limited with I<keytype>
63and I<selection>, which specifies the expected resulting keytype and contents.
64NULL and zero are valid and signify that the decoder implementations will
65find out the keytype and key contents on their own from the input they get.
66
67If no suitable decoder implementation is found,
68OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but
69with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
70zero).  This helps the caller to distinguish between an error when creating
71the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
72act accordingly.
73
74OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
75use when decrypting the encoded private key. Alternatively, a pass phrase
76callback may be specified with the following functions.
77
78OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
79and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
80implementation can use to prompt for a pass phrase, giving the caller the
81choice of preferred pass phrase callback form.  These are called indirectly,
82through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
83
84The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
85be re-used in all decodings that are performed in the same decoding run (for
86example, within one L<OSSL_DECODER_from_bio(3)> call).
87
88=head2 Input Types
89
90Available input types depend on the implementations that available providers
91offer, and provider documentation should have the details.
92
93Among the known input types that OpenSSL decoder implementations offer
94for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>.
95See L<openssl-glossary(7)> for further information on what these input
96types mean.
97
98=head2 Input Structures
99
100Available input structures depend on the implementations that available
101providers offer, and provider documentation should have the details.
102
103Among the known input structures that OpenSSL decoder implementations
104offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>.
105
106OpenSSL decoder implementations also support the input structure
107C<type-specific>.  This is the structure used for keys encoded
108according to key type specific specifications.  For example, RSA keys
109encoded according to PKCS#1.
110
111=head2 Selections
112
113I<selection> can be any one of the values described in
114L<EVP_PKEY_fromdata(3)/Selections>.
115Additionally I<selection> can also be set to B<0> to indicate that the code will
116auto detect the selection.
117
118=head1 RETURN VALUES
119
120OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a
121B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
122
123OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
124OSSL_DECODER_CTX_set_passphrase_ui() and
125OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
126failure.
127
128=head1 SEE ALSO
129
130L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
131
132=head1 HISTORY
133
134The functions described here were added in OpenSSL 3.0.
135
136=head1 COPYRIGHT
137
138Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
139
140Licensed under the Apache License 2.0 (the "License").  You may not use
141this file except in compliance with the License.  You can obtain a copy
142in the file LICENSE in the source distribution or at
143L<https://www.openssl.org/source/license.html>.
144
145=cut
146