5 OSSL_DECODER_CTX_new_by_EVP_PKEY,
6 OSSL_DECODER_CTX_set_passphrase,
7 OSSL_DECODER_CTX_set_pem_password_cb,
8 OSSL_DECODER_CTX_set_passphrase_ui,
9 OSSL_DECODER_CTX_set_passphrase_cb
10 - Decoder routines to decode EVP_PKEYs
14 #include <openssl/decoder.h>
17 OSSL_DECODER_CTX_new_by_EVP_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);
23 int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
24 const unsigned char *kstr,
26 int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
29 int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
30 const UI_METHOD *ui_method,
32 int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
33 OSSL_PASSPHRASE_CALLBACK *cb,
38 OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
39 B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
40 them up, so all the caller has to do next is call functions like
41 L<OSSL_DECODER_from_bio(3)>. The caller may use the optional I<input_type>,
42 I<input_struct>, I<keytype> and I<selection> to specify what the input is
45 Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available
46 L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
47 decoder implementations that may be able to process the encoded input into
48 data suitable for B<EVP_PKEY>s. All these implementations are implicitly
49 fetched using I<libctx> and I<propquery>.
51 The search of decoder implementations can be limited with I<input_type> and
52 I<input_struct> which specifies a starting input type and input structure.
53 NULL is valid for both of them and signifies that the decoder implementations
54 will find out the input type on their own.
55 They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and
56 L<OSSL_DECODER_CTX_set_input_structure(3)>.
57 See L</Input Types> and L</Input Structures> below for further information.
59 The search of decoder implementations can also be limited with I<keytype>
60 and I<selection>, which specifies the expected resulting keytype and contents.
61 NULL and zero are valid and signify that the decoder implementations will
62 find out the keytype and key contents on their own from the input they get.
64 If no suitable decoder implementation is found,
65 OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_DECODER_CTX>, but
66 with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
67 zero). This helps the caller to distinguish between an error when creating
68 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
71 OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
72 use when decrypting the encoded private key. Alternatively, a pass phrase
73 callback may be specified with the following functions.
75 OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
76 and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
77 implementation can use to prompt for a pass phrase, giving the caller the
78 choice of prefered pass phrase callback form. These are called indirectly,
79 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
81 The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
82 be re-used in all decodings that are performed in the same decoding run (for
83 example, within one L<OSSL_DECODER_from_bio(3)> call).
87 Available input types depend on the implementations that available providers
88 offer, and provider documentation should have the details.
90 Among the known input types that OpenSSL decoder implementations offer
91 for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>.
92 See L<openssl-glossary(7)> for further information on what these input
95 =head2 Input Structures
97 Available input structures depend on the implementations that available
98 providers offer, and provider documentation should have the details.
100 Among the known input structures that OpenSSL decoder implementations
101 offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>.
103 OpenSSL decoder implementations also support the input structure
104 C<type-specific>. This is the structure used for keys encoded
105 according to key type specific specifications. For example, RSA keys
106 encoded according to PKCS#1.
110 OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
111 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
113 OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
114 OSSL_DECODER_CTX_set_passphrase_ui() and
115 OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
120 Parts of the function names are made to match already existing OpenSSL
123 B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type name,
124 thus making for the naming pattern B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when
125 new types are handled.
129 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
133 The functions described here were added in OpenSSL 3.0.
137 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
139 Licensed under the Apache License 2.0 (the "License"). You may not use
140 this file except in compliance with the License. You can obtain a copy
141 in the file LICENSE in the source distribution or at
142 L<https://www.openssl.org/source/license.html>.