diff options
author | Richard Levitte <levitte@openssl.org> | 2020-10-09 13:02:58 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-10-30 13:09:52 +0100 |
commit | 140eee2b3b3090107aea2d09ab10eb737fb1e5bb (patch) | |
tree | d9da74dea16ae5ce298509fe5eb96fb1ee386b7f /doc | |
parent | f79289389edef63b76c6c2a3042435dda7d42dfd (diff) |
Add easy to digest selector macros for EVP_PKEYs
These are meant to be used with functions like
OSSL_ENCODER_CTX_new_by_EVP_PKEY()
The OSSL_ENCODER_CTX_new_by_EVP_PKEY() manual is also expanded on the
topics of output types and selections.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13189)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod | 69 |
1 files changed, 68 insertions, 1 deletions
diff --git a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod index b47dc453f8..f90d13d551 100644 --- a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod +++ b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod @@ -39,7 +39,11 @@ OSSL_ENCODER_CTX_set_passphrase_ui 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)>. +L<OSSL_ENCODER_to_bio(3)>. I<output_type> determines the final output +encoding, and I<selection> can be used to select what parts of the I<pkey> +should be included in the output. I<output_type> is further discussed in +L</Output types> below, and I<selection> is further described in +L</Selections>. 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 @@ -75,6 +79,69 @@ 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. +=head2 Output types + +The possible B<EVP_PKEY> output types depends on the available +implementations. + +OpenSSL has built in implementations for the following output types: + +=over 4 + +=item C<TEXT> + +The output is a human readable description of the key. +L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_public(3)> and +L<EVP_PKEY_print_params(3)> use this for their output. + +=item C<DER> + +The output is the DER encoding of the I<selection> of the I<pkey>. + +=item C<PEM> + +The output is the I<selection> of the I<pkey> in PEM format. + +=back + +=head2 Selections + +=begin comment + +These constants should really be documented among the EVP manuals, but this +will have to do for now. + +=end comment + +The following constants can be used for standard I<selection>: + +=over 4 + +=item B<EVP_PKEY_KEY_PARAMETERS> + +Indicates that only the key parameters should be included in the output. +Where it matters, the data type in the output will indicate that the data is +parameters, not a key. + +=item B<EVP_PKEY_PUBLIC_KEY> + +Indicates that the public key and eventual key parameters will be included +in the output. Where it matters, the data type in the output will indicate +that the data is a public key. + +=item B<EVP_PKEY_KEYPAIR> + +Indicates that the private key, the public key and eventual key parameters +should be included in the output. Where it matters, the data type in the +output will indicate that the data is a private key. + +=back + +These are only indications, the encoder implementations are free to +determine what makes sense to include in the output, and this may depend on +the desired output. For example, an EC key in a PKCS#8 structure doesn't +usually include the public key. + =head1 RETURN VALUES OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a |