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(const EVP_PKEY *pkey, const char *input_type,
18 OPENSSL_CTX *libctx, const char *propquery);
20 int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
21 const unsigned char *kstr,
23 int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
26 int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
27 const UI_METHOD *ui_method,
29 int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
30 OSSL_PASSPHRASE_CALLBACK *cb,
35 OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that
36 creates a B<OSSL_DECODER_CTX>, finds all applicable decoder
37 implementations and sets them up, so all the caller has to do next is
38 call functions like OSSL_DECODE_from_bio().
40 Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all
41 available L<EVP_KEYMGMT(3)> implementations, and then builds a list of all
42 potential decoder implementations that may be able to process the
43 encoded input into data suitable for B<EVP_PKEY>s. All these
44 implementations are implicitly fetched using I<libctx> and I<propquery>.
46 The search of decoder implementations can be limited with
47 I<input_type>, which specifies a starting input type. This is further
48 explained in L<OSSL_DECODER_CTX_set_input_type(3)>.
50 If no suitable decoder was found, OSSL_DECODER_CTX_new_by_EVP_PKEY()
51 still creates a B<OSSL_DECODER_CTX>, but with no associated
52 decoder (L<OSSL_DECODER_CTX_num_decoders(3)> returns
53 zero). This helps the caller distinguish between an error when
54 creating the B<OSSL_DECODER_CTX>, and the lack the decoder
55 support and act accordingly.
57 OSSL_DECODER_CTX_set_passphrase() gives the implementation a
58 pass phrase to use when decrypting the encoded private key.
59 Alternatively, a pass phrase callback may be specified with the
62 OSSL_DECODER_CTX_set_pem_password_cb(),
63 OSSL_DECODER_CTX_set_passphrase_ui() and
64 OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that
65 the implementation can use to prompt for a pass phrase, giving the caller
66 the choice of prefered pass phrase callback form. These are called
67 indirectly, through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
69 The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase,
70 to be re-used in all decodings that are performed in the same decoding run
71 (for example, within one L<OSSL_DECODER_from_bio(3)> call).
75 OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
76 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
78 OSSL_DECODER_CTX_set_passphrase(),
79 OSSL_DECODER_CTX_set_pem_password_cb(),
80 OSSL_DECODER_CTX_set_passphrase_ui() and
81 OSSL_DECODER_CTX_set_passphrase_cb()
82 all return 1 on success, or 0 on failure.
86 Parts of the function names are made to match already existing OpenSSL
89 B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type
90 name, thus making for the naming pattern
91 B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when new types are handled.
95 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
99 The functions described here were added in OpenSSL 3.0.
103 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
105 Licensed under the Apache License 2.0 (the "License"). You may not use
106 this file except in compliance with the License. You can obtain a copy
107 in the file LICENSE in the source distribution or at
108 L<https://www.openssl.org/source/license.html>.