OSSL_ENCODER_CTX_new_by_EVP_PKEY,
OSSL_ENCODER_CTX_set_cipher,
OSSL_ENCODER_CTX_set_passphrase,
+OSSL_ENCODER_CTX_set_pem_password_cb,
OSSL_ENCODER_CTX_set_passphrase_cb,
-OSSL_ENCODER_CTX_set_passphrase_ui,
-OSSL_ENCODER_PUBKEY_TO_PEM_PQ,
-OSSL_ENCODER_PrivateKey_TO_PEM_PQ,
-OSSL_ENCODER_Parameters_TO_PEM_PQ,
-OSSL_ENCODER_PUBKEY_TO_DER_PQ,
-OSSL_ENCODER_PrivateKey_TO_DER_PQ,
-OSSL_ENCODER_Parameters_TO_DER_PQ,
-OSSL_ENCODER_PUBKEY_TO_TEXT_PQ,
-OSSL_ENCODER_PrivateKey_TO_TEXT_PQ,
-OSSL_ENCODER_Parameters_TO_TEXT_PQ
+OSSL_ENCODER_CTX_set_passphrase_ui
- Encoder routines to encode EVP_PKEYs
=head1 SYNOPSIS
#include <openssl/encoder.h>
- OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
- const char *propquery);
+ OSSL_ENCODER_CTX *
+ OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
+ const char *output_type, int selection,
+ OPENSSL_CTX *libctx, const char *propquery);
int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx,
const char *cipher_name,
int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx,
const unsigned char *kstr,
size_t klen);
- int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
- pem_password_cb *cb, void *cbarg);
+ int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx,
+ pem_password_cb *cb, void *cbarg);
int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx,
const UI_METHOD *ui_method,
void *ui_data);
-
- #define OSSL_ENCODER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
- #define OSSL_ENCODER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
-
- #define OSSL_ENCODER_PUBKEY_TO_DER_PQ "format=der,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_DER_PQ "format=der,type=private"
- #define OSSL_ENCODER_Parameters_TO_DER_PQ "format=der,type=parameters"
-
- #define OSSL_ENCODER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
- #define OSSL_ENCODER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
+ int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
+ OSSL_PASSPHRASE_CALLBACK *cb,
+ void *cbarg);
=head1 DESCRIPTION
-OSSL_ENCODER_CTX_new_by_EVP_PKEY() creates a B<OSSL_ENCODER_CTX>
-with a suitable attached output routine for B<EVP_PKEY>s. It will
-search for a encoder implementation that matches the algorithm of
-the B<EVP_PKEY> and the property query given with I<propquery>. It
-will prefer to find a encoder from the same provider as the key
-data of the B<EVP_PKEY> itself, but failing that, it will choose the
-first encoder that supplies a generic encoding function.
-
-If no suitable encoder was found, OSSL_ENCODER_CTX_new_by_EVP_PKEY()
-still creates a B<OSSL_ENCODER_CTX>, but with no associated
-encoder (L<OSSL_ENCODER_CTX_get_encoder(3)> returns NULL).
-This helps the caller distinguish between an error when creating
-the B<OSSL_ENCODER_CTX>, and the lack the encoder support and
+OSSL_ENCODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
+B<OSSL_ENCODER_CTX>, finds all applicable encoder implementations and sets
+them up, so almost all the caller has to do next is call functions like
+L<OSSL_ENCODER_to_bio(3)>.
+
+Internally, OSSL_ENCODER_CTX_new_by_EVP_PKEY() uses the names from the
+L<EVP_KEYMGMT(3)> implementation associated with I<pkey> to build a list of
+applicable encoder implementations that are used to process the I<pkey> into
+the encoding named by I<output_type>. All these implementations are
+implicitly fetched using I<libctx> and I<propquery>.
+
+If no suitable encoder implementation is found,
+OSSL_ENCODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_ENCODER_CTX>, but
+with no associated encoder (L<OSSL_ENCODER_CTX_get_num_encoders(3)> returns
+zero). This helps the caller to distinguish between an error when creating
+the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
act accordingly.
OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher
should be used to encrypt encoded keys. The cipher is given by
name I<cipher_name>. The interpretation of that I<cipher_name> is
-implementation dependent. The implementation may implement the digest
+implementation dependent. The implementation may implement the cipher
directly itself or by other implementations, or it may choose to fetch
it. If the implementation supports fetching the cipher, then it may
use I<propquery> as properties to be queried for when fetching.
Alternatively, a pass phrase callback may be specified with the
following functions.
-OSSL_ENCODER_CTX_set_passphrase_cb() and
-OSSL_ENCODER_CTX_set_passphrase_ui() sets up a callback method that
-the implementation can use to prompt for a pass phrase.
-
-=for comment Note that the callback method is called indirectly,
+OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
+and OSSL_ENCODER_CTX_set_passphrase_cb() sets 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 macros B<OSSL_ENCODER_PUBKEY_TO_PEM_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_PEM_PQ>,
-B<OSSL_ENCODER_Parameters_TO_PEM_PQ>,
-B<OSSL_ENCODER_PUBKEY_TO_DER_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_DER_PQ>,
-B<OSSL_ENCODER_Parameters_TO_DER_PQ>,
-B<OSSL_ENCODER_PUBKEY_TO_TEXT_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_TEXT_PQ>,
-B<OSSL_ENCODER_Parameters_TO_TEXT_PQ> are convenience macros with
-property queries to encode the B<EVP_PKEY> as a public key, private
-key or parameters to B<PEM>, to B<DER>, or to text.
-
=head1 RETURN VALUES
OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a
B<OSSL_ENCODER_CTX>, or NULL if it couldn't be created.
-OSSL_ENCODER_CTX_set_cipher(),
-OSSL_ENCODER_CTX_set_passphrase(),
-OSSL_ENCODER_CTX_set_passphrase_cb(), and
-OSSL_ENCODER_CTX_set_passphrase_ui() all return 1 on success, or 0
-on failure.
+OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(),
+OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
+and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
+failure.
=head1 NOTES
-Parts of the function and macro names are made to match already
-existing OpenSSL names.
-
-B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type
-name, thus making for the naming pattern
-B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when new types are handled.
+Parts of the function names are made to match already existing OpenSSL
+names.
-B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
-the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
-as B<i2d_I<TYPE>_bio> functions.
+B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type name,
+thus making for the naming pattern B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when
+new types are handled.
=head1 SEE ALSO
projects / openssl.git / blobdiff