1=pod 2 3=head1 NAME 4 5OSSL_DECODER_CTX_new_for_pkey, 6OSSL_DECODER_CTX_set_passphrase, 7OSSL_DECODER_CTX_set_pem_password_cb, 8OSSL_DECODER_CTX_set_passphrase_ui, 9OSSL_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_for_pkey(EVP_PKEY **pkey, 18 const char *input_type, 19 const char *input_struct, 20 const char *keytype, int selection, 21 OSSL_LIB_CTX *libctx, const char *propquery); 22 23 int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx, 24 const unsigned char *kstr, 25 size_t klen); 26 int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx, 27 pem_password_cb *cb, 28 void *cbarg); 29 int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx, 30 const UI_METHOD *ui_method, 31 void *ui_data); 32 int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx, 33 OSSL_PASSPHRASE_CALLBACK *cb, 34 void *cbarg); 35 36=head1 DESCRIPTION 37 38OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a 39B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets 40them up, so all the caller has to do next is call functions like 41L<OSSL_DECODER_from_bio(3)>. The caller may use the optional I<input_type>, 42I<input_struct>, I<keytype> and I<selection> to specify what the input is 43expected to contain. The I<pkey> must reference an B<EVP_PKEY *> variable 44that will be set to the newly created B<EVP_PKEY> on succesfull decoding. 45The referenced variable must be initialized to NULL before calling the 46function. 47 48Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available 49L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential 50decoder implementations that may be able to process the encoded input into 51data suitable for B<EVP_PKEY>s. All these implementations are implicitly 52fetched using I<libctx> and I<propquery>. 53 54The search of decoder implementations can be limited with I<input_type> and 55I<input_struct> which specifies a starting input type and input structure. 56NULL is valid for both of them and signifies that the decoder implementations 57will find out the input type on their own. 58They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and 59L<OSSL_DECODER_CTX_set_input_structure(3)>. 60See L</Input Types> and L</Input Structures> below for further information. 61 62The search of decoder implementations can also be limited with I<keytype> 63and I<selection>, which specifies the expected resulting keytype and contents. 64NULL and zero are valid and signify that the decoder implementations will 65find out the keytype and key contents on their own from the input they get. 66 67If no suitable decoder implementation is found, 68OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but 69with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns 70zero). This helps the caller to distinguish between an error when creating 71the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to 72act accordingly. 73 74OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to 75use when decrypting the encoded private key. Alternatively, a pass phrase 76callback may be specified with the following functions. 77 78OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() 79and OSSL_DECODER_CTX_set_passphrase_cb() set 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 84The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to 85be re-used in all decodings that are performed in the same decoding run (for 86example, within one L<OSSL_DECODER_from_bio(3)> call). 87 88=head2 Input Types 89 90Available input types depend on the implementations that available providers 91offer, and provider documentation should have the details. 92 93Among the known input types that OpenSSL decoder implementations offer 94for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>. 95See L<openssl-glossary(7)> for further information on what these input 96types mean. 97 98=head2 Input Structures 99 100Available input structures depend on the implementations that available 101providers offer, and provider documentation should have the details. 102 103Among the known input structures that OpenSSL decoder implementations 104offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>. 105 106OpenSSL decoder implementations also support the input structure 107C<type-specific>. This is the structure used for keys encoded 108according to key type specific specifications. For example, RSA keys 109encoded according to PKCS#1. 110 111=head2 Selections 112 113I<selection> can be any one of the values described in 114L<EVP_PKEY_fromdata(3)/Selections>. 115Additionally I<selection> can also be set to B<0> to indicate that the code will 116auto detect the selection. 117 118=head1 RETURN VALUES 119 120OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a 121B<OSSL_DECODER_CTX>, or NULL if it couldn't be created. 122 123OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(), 124OSSL_DECODER_CTX_set_passphrase_ui() and 125OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on 126failure. 127 128=head1 SEE ALSO 129 130L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)> 131 132=head1 HISTORY 133 134The functions described here were added in OpenSSL 3.0. 135 136=head1 COPYRIGHT 137 138Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 139 140Licensed under the Apache License 2.0 (the "License"). You may not use 141this file except in compliance with the License. You can obtain a copy 142in the file LICENSE in the source distribution or at 143L<https://www.openssl.org/source/license.html>. 144 145=cut 146