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