4190c4232bf8deccaaa53f2b6e203193dbbd9972
[openssl.git] / doc / man3 / OSSL_DECODER_CTX_new_by_EVP_PKEY.pod
1 =pod
2
3 =head1 NAME
4
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
11
12 =head1 SYNOPSIS
13
14  #include <openssl/decoder.h>
15
16  OSSL_DECODER_CTX *
17  OSSL_DECODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, const char *input_type,
18                                   OPENSSL_CTX *libctx, const char *propquery);
19
20  int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
21                                      const unsigned char *kstr,
22                                      size_t klen);
23  int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
24                                           pem_password_cb *cb,
25                                           void *cbarg);
26  int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
27                                         const UI_METHOD *ui_method,
28                                         void *ui_data);
29  int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
30                                         OSSL_PASSPHRASE_CALLBACK *cb,
31                                         void *cbarg);
32
33 =head1 DESCRIPTION
34
35 OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
36 B<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_DECODE_from_bio().
39
40 Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available
41 L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
42 decoder implementations that may be able to process the encoded input into
43 data suitable for B<EVP_PKEY>s.  All these implementations are implicitly
44 fetched using I<libctx> and I<propquery>.
45
46 The search of decoder implementations can be limited with I<input_type>,
47 which specifies a starting input type.  This is further explained in
48 L<OSSL_DECODER_CTX_set_input_type(3)>.
49
50 If no suitable decoder implementation is found,
51 OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_DECODER_CTX>, but
52 with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
53 zero).  This helps the caller to distinguish between an error when creating
54 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
55 act accordingly.
56
57 OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
58 use when decrypting the encoded private key. Alternatively, a pass phrase
59 callback may be specified with the following functions.
60
61 OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
62 and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
63 implementation can use to prompt for a pass phrase, giving the caller the
64 choice of prefered pass phrase callback form.  These are called indirectly,
65 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
66
67 The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
68 be re-used in all decodings that are performed in the same decoding run (for
69 example, within one L<OSSL_DECODER_from_bio(3)> call).
70
71 =head1 RETURN VALUES
72
73 OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
74 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
75
76 OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
77 OSSL_DECODER_CTX_set_passphrase_ui() and
78 OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
79 failure.
80
81 =head1 NOTES
82
83 Parts of the function names are made to match already existing OpenSSL
84 names.
85
86 B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type name,
87 thus making for the naming pattern B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when
88 new types are handled.
89
90 =head1 SEE ALSO
91
92 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
93
94 =head1 HISTORY
95
96 The functions described here were added in OpenSSL 3.0.
97
98 =head1 COPYRIGHT
99
100 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
101
102 Licensed under the Apache License 2.0 (the "License").  You may not use
103 this file except in compliance with the License.  You can obtain a copy
104 in the file LICENSE in the source distribution or at
105 L<https://www.openssl.org/source/license.html>.
106
107 =cut