1=pod
2
3=head1 NAME
4
5OSSL_ENCODER_CTX_new_for_pkey,
6OSSL_ENCODER_CTX_set_cipher,
7OSSL_ENCODER_CTX_set_passphrase,
8OSSL_ENCODER_CTX_set_pem_password_cb,
9OSSL_ENCODER_CTX_set_passphrase_cb,
10OSSL_ENCODER_CTX_set_passphrase_ui
11- Encoder routines to encode EVP_PKEYs
12
13=head1 SYNOPSIS
14
15 #include <openssl/encoder.h>
16
17 OSSL_ENCODER_CTX *
18 OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, int selection,
19                               const char *output_type,
20                               const char *output_structure,
21                               const char *propquery);
22
23 int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx,
24                                 const char *cipher_name,
25                                 const char *propquery);
26 int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx,
27                                     const unsigned char *kstr,
28                                     size_t klen);
29 int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx,
30                                          pem_password_cb *cb, void *cbarg);
31 int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx,
32                                        const UI_METHOD *ui_method,
33                                        void *ui_data);
34 int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
35                                        OSSL_PASSPHRASE_CALLBACK *cb,
36                                        void *cbarg);
37
38=head1 DESCRIPTION
39
40OSSL_ENCODER_CTX_new_for_pkey() is a utility function that creates a
41B<OSSL_ENCODER_CTX>, finds all applicable encoder implementations and sets
42them up, so almost all the caller has to do next is call functions like
43L<OSSL_ENCODER_to_bio(3)>.  I<output_type> determines the final output
44encoding, and I<selection> can be used to select what parts of the I<pkey>
45should be included in the output.  I<output_type> is further discussed in
46L</Output types> below, and I<selection> is further described in
47L</Selections>.
48
49Internally, OSSL_ENCODER_CTX_new_for_pkey() uses the names from the
50L<EVP_KEYMGMT(3)> implementation associated with I<pkey> to build a list of
51applicable encoder implementations that are used to process the I<pkey> into
52the encoding named by I<output_type>, with the outermost structure named by
53I<output_structure> if that's relevant.  All these implementations are
54implicitly fetched, with I<propquery> for finer selection.
55
56If no suitable encoder implementation is found,
57OSSL_ENCODER_CTX_new_for_pkey() still creates a B<OSSL_ENCODER_CTX>, but
58with no associated encoder (L<OSSL_ENCODER_CTX_get_num_encoders(3)> returns
59zero).  This helps the caller to distinguish between an error when creating
60the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
61act accordingly.
62
63OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher
64should be used to encrypt encoded keys.  The cipher is given by
65name I<cipher_name>.  The interpretation of that I<cipher_name> is
66implementation dependent.  The implementation may implement the cipher
67directly itself or by other implementations, or it may choose to fetch
68it.  If the implementation supports fetching the cipher, then it may
69use I<propquery> as properties to be queried for when fetching.
70I<cipher_name> may also be NULL, which will result in unencrypted
71encoding.
72
73OSSL_ENCODER_CTX_set_passphrase() gives the implementation a
74pass phrase to use when encrypting the encoded private key.
75Alternatively, a pass phrase callback may be specified with the
76following functions.
77
78OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
79and OSSL_ENCODER_CTX_set_passphrase_cb() sets up a callback method that the
80implementation can use to prompt for a pass phrase, giving the caller the
81choice of prefered pass phrase callback form.  These are called indirectly,
82through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
83
84=head2 Output types
85
86The possible B<EVP_PKEY> output types depends on the available
87implementations.
88
89OpenSSL has built in implementations for the following output types:
90
91=over 4
92
93=item C<TEXT>
94
95The output is a human readable description of the key.
96L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_public(3)> and
97L<EVP_PKEY_print_params(3)> use this for their output.
98
99=item C<DER>
100
101The output is the DER encoding of the I<selection> of the I<pkey>.
102
103=item C<PEM>
104
105The output is the I<selection> of the I<pkey> in PEM format.
106
107=back
108
109=head2 Selections
110
111I<selection> can be any one of the values described in
112L<EVP_PKEY_fromdata(3)/Selections>.
113
114These are only 'hints' since the encoder implementations are free to
115determine what makes sense to include in the output, and this may depend on
116the desired output.  For example, an EC key in a PKCS#8 structure doesn't
117usually include the public key.
118
119=head1 RETURN VALUES
120
121OSSL_ENCODER_CTX_new_for_pkey() returns a pointer to an B<OSSL_ENCODER_CTX>,
122or NULL if it couldn't be created.
123
124OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(),
125OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
126and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
127failure.
128
129=head1 SEE ALSO
130
131L<provider(7)>, L<OSSL_ENCODER(3)>, L<OSSL_ENCODER_CTX(3)>
132
133=head1 HISTORY
134
135The functions described here were added in OpenSSL 3.0.
136
137=head1 COPYRIGHT
138
139Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
140
141Licensed under the Apache License 2.0 (the "License").  You may not use
142this file except in compliance with the License.  You can obtain a copy
143in the file LICENSE in the source distribution or at
144L<https://www.openssl.org/source/license.html>.
145
146=cut
147