1OSSL_DECODER_CTX_NEW_FOR_PKEY(3ossl)OpenSSLOSSL_DECODER_CTX_NEW_FOR_PKEY(3ossl)
2
3
4

NAME

6       OSSL_DECODER_CTX_new_for_pkey, OSSL_DECODER_CTX_set_passphrase,
7       OSSL_DECODER_CTX_set_pem_password_cb,
8       OSSL_DECODER_CTX_set_passphrase_ui, OSSL_DECODER_CTX_set_passphrase_cb
9       - Decoder routines to decode EVP_PKEYs
10

SYNOPSIS

12        #include <openssl/decoder.h>
13
14        OSSL_DECODER_CTX *
15        OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
16                                      const char *input_type,
17                                      const char *input_struct,
18                                      const char *keytype, int selection,
19                                      OSSL_LIB_CTX *libctx, const char *propquery);
20
21        int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
22                                            const unsigned char *kstr,
23                                            size_t klen);
24        int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
25                                                 pem_password_cb *cb,
26                                                 void *cbarg);
27        int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
28                                               const UI_METHOD *ui_method,
29                                               void *ui_data);
30        int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
31                                               OSSL_PASSPHRASE_CALLBACK *cb,
32                                               void *cbarg);
33

DESCRIPTION

35       OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
36       OSSL_DECODER_CTX, finds all applicable decoder implementations and sets
37       them up, so all the caller has to do next is call functions like
38       OSSL_DECODER_from_bio(3).  The caller may use the optional input_type,
39       input_struct, keytype and selection to specify what the input is
40       expected to contain.  The pkey must reference an EVP_PKEY * variable
41       that will be set to the newly created EVP_PKEY on succesfull decoding.
42       The referenced variable must be initialized to NULL before calling the
43       function.
44
45       Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available
46       EVP_KEYMGMT(3) implementations, and then builds a list of all potential
47       decoder implementations that may be able to process the encoded input
48       into data suitable for EVP_PKEYs.  All these implementations are
49       implicitly fetched using libctx and propquery.
50
51       The search of decoder implementations can be limited with input_type
52       and input_struct which specifies a starting input type and input
53       structure.  NULL is valid for both of them and signifies that the
54       decoder implementations will find out the input type on their own.
55       They are set with OSSL_DECODER_CTX_set_input_type(3) and
56       OSSL_DECODER_CTX_set_input_structure(3).  See "Input Types" and "Input
57       Structures" below for further information.
58
59       The search of decoder implementations can also be limited with keytype
60       and selection, which specifies the expected resulting keytype and
61       contents.  NULL and zero are valid and signify that the decoder
62       implementations will find out the keytype and key contents on their own
63       from the input they get.
64
65       If no suitable decoder implementation is found,
66       OSSL_DECODER_CTX_new_for_pkey() still creates a OSSL_DECODER_CTX, but
67       with no associated decoder (OSSL_DECODER_CTX_get_num_decoders(3)
68       returns zero).  This helps the caller to distinguish between an error
69       when creating the OSSL_ENCODER_CTX and missing encoder implementation,
70       and allows it to act accordingly.
71
72       OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass
73       phrase to use when decrypting the encoded private key. Alternatively, a
74       pass phrase callback may be specified with the following functions.
75
76       OSSL_DECODER_CTX_set_pem_password_cb(),
77       OSSL_DECODER_CTX_set_passphrase_ui() and
78       OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
79       implementation can use to prompt for a pass phrase, giving the caller
80       the choice of prefered pass phrase callback form.  These are called
81       indirectly, through an internal OSSL_PASSPHRASE_CALLBACK function.
82
83       The internal OSSL_PASSPHRASE_CALLBACK function caches the pass phrase,
84       to be re-used in all decodings that are performed in the same decoding
85       run (for example, within one OSSL_DECODER_from_bio(3) call).
86
87   Input Types
88       Available input types depend on the implementations that available
89       providers offer, and provider documentation should have the details.
90
91       Among the known input types that OpenSSL decoder implementations offer
92       for EVP_PKEYs are "DER", "PEM", "MSBLOB" and "PVK".  See
93       openssl-glossary(7) for further information on what these input types
94       mean.
95
96   Input Structures
97       Available input structures depend on the implementations that available
98       providers offer, and provider documentation should have the details.
99
100       Among the known input structures that OpenSSL decoder implementations
101       offer for EVP_PKEYs are "pkcs8" and "SubjectPublicKeyInfo".
102
103       OpenSSL decoder implementations also support the input structure
104       "type-specific".  This is the structure used for keys encoded according
105       to key type specific specifications.  For example, RSA keys encoded
106       according to PKCS#1.
107
108   Selections
109       selection can be any one of the values described in "Selections" in
110       EVP_PKEY_fromdata(3).  Additionally selection can also be set to 0 to
111       indicate that the code will auto detect the selection.
112

RETURN VALUES

114       OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a
115       OSSL_DECODER_CTX, or NULL if it couldn't be created.
116
117       OSSL_DECODER_CTX_set_passphrase(),
118       OSSL_DECODER_CTX_set_pem_password_cb(),
119       OSSL_DECODER_CTX_set_passphrase_ui() and
120       OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
121       failure.
122

SEE ALSO

124       provider(7), OSSL_DECODER(3), OSSL_DECODER_CTX(3)
125

HISTORY

127       The functions described here were added in OpenSSL 3.0.
128
130       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
131
132       Licensed under the Apache License 2.0 (the "License").  You may not use
133       this file except in compliance with the License.  You can obtain a copy
134       in the file LICENSE in the source distribution or at
135       <https://www.openssl.org/source/license.html>.
136
137
138
1393.0.5                             2022-07-0O5SSL_DECODER_CTX_NEW_FOR_PKEY(3ossl)
Impressum