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