mirror of https://github.com/openssl/openssl.git
110 lines
4.0 KiB
Plaintext
110 lines
4.0 KiB
Plaintext
|
=pod
|
||
|
|
|
||
|
|
=head1 NAME
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_new_by_EVP_PKEY,
|
||
|
|
OSSL_DECODER_CTX_set_passphrase,
|
||
|
|
OSSL_DECODER_CTX_set_pem_password_cb,
|
||
|
|
OSSL_DECODER_CTX_set_passphrase_ui
|
||
|
|
- Decoder routines to decode EVP_PKEYs
|
||
|
|
|
||
|
|
=head1 SYNOPSIS
|
||
|
|
|
||
|
|
#include <openssl/decoder.h>
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX *
|
||
|
|
OSSL_DECODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, const char *input_type,
|
||
|
|
OPENSSL_CTX *libctx, const char *propquery);
|
||
|
|
|
||
|
|
int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
|
||
|
|
const unsigned char *kstr,
|
||
|
|
size_t klen);
|
||
|
|
int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
|
||
|
|
pem_password_cb *cb,
|
||
|
|
void *cbarg);
|
||
|
|
int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
|
||
|
|
const UI_METHOD *ui_method,
|
||
|
|
void *ui_data);
|
||
|
|
|
||
|
|
=head1 DESCRIPTION
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that
|
||
|
|
creates a B<OSSL_DECODER_CTX>, finds all applicable decoder
|
||
|
|
implementations and sets them up, so all the caller has to do next is
|
||
|
|
call functions like OSSL_DECODE_from_bio().
|
||
|
|
|
||
|
|
Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all
|
||
|
|
available L<EVP_KEYMGMT(3)> implementations, and then builds a list of all
|
||
|
|
potential decoder implementations that may be able to process the
|
||
|
|
encoded input into data suitable for B<EVP_PKEY>s. All these
|
||
|
|
implementations are implicitly fetched using I<libctx> and I<propquery>.
|
||
|
|
|
||
|
|
The search of decoder implementations can be limited with
|
||
|
|
I<input_type>, which specifies a starting input type. This is further
|
||
|
|
explained in L<OSSL_DECODER_CTX_set_input_type(3)>.
|
||
|
|
|
||
|
|
If no suitable decoder was found, OSSL_DECODER_CTX_new_by_EVP_PKEY()
|
||
|
|
still creates a B<OSSL_DECODER_CTX>, but with no associated
|
||
|
|
decoder (L<OSSL_DECODER_CTX_num_decoders(3)> returns
|
||
|
|
zero). This helps the caller distinguish between an error when
|
||
|
|
creating the B<OSSL_DECODER_CTX>, and the lack the decoder
|
||
|
|
support and act accordingly.
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_set_passphrase() gives the implementation a
|
||
|
|
pass phrase to use when decrypting the encoded private key.
|
||
|
|
Alternatively, a pass phrase callback may be specified with the
|
||
|
|
following functions.
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_set_pem_password_cb() and
|
||
|
|
OSSL_DECODER_CTX_set_passphrase_ui() set up a callback method that
|
||
|
|
the implementation can use to prompt for a pass phrase, giving the caller
|
||
|
|
the choice of prefered pass phrase callback form. These are called
|
||
|
|
indirectly, through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
|
||
|
|
|
||
|
|
The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
|
||
|
|
be re-used in all decodings that are performed in the same
|
||
|
|
decoding run
|
||
|
|
(for example, within one L<OSSL_DECODER_from_bio(3)> call).
|
||
|
|
|
||
|
|
=for comment the name OSSL_DECODER_CTX_set_pem_password_cb() leaves
|
||
|
|
open the future possibility of having a function where the caller can set a
|
||
|
|
B<OSSL_PASSPHRASE_CALLBACK> method as another option.
|
||
|
|
|
||
|
|
=head1 RETURN VALUES
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
|
||
|
|
B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
|
||
|
|
|
||
|
|
OSSL_DECODER_CTX_set_passphrase(),
|
||
|
|
OSSL_DECODER_CTX_set_pem_password_cb() and
|
||
|
|
OSSL_DECODER_CTX_set_passphrase_ui()
|
||
|
|
all return 1 on success, or 0 on failure.
|
||
|
|
|
||
|
|
=head1 NOTES
|
||
|
|
|
||
|
|
Parts of the function names are made to match already existing OpenSSL
|
||
|
|
names.
|
||
|
|
|
||
|
|
B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type
|
||
|
|
name, thus making for the naming pattern
|
||
|
|
B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when new types are handled.
|
||
|
|
|
||
|
|
=head1 SEE ALSO
|
||
|
|
|
||
|
|
L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
|
||
|
|
|
||
|
|
=head1 HISTORY
|
||
|
|
|
||
|
|
The functions described here were added in OpenSSL 3.0.
|
||
|
|
|
||
|
|
=head1 COPYRIGHT
|
||
|
|
|
||
|
|
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
|
||
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file LICENSE in the source distribution or at
|
||
|
|
L<https://www.openssl.org/source/license.html>.
|
||
|
|
|
||
|
|
=cut
|