#include <openssl/decoder.h>
OSSL_DECODER_CTX *
- OSSL_DECODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
- const char *input_type, const char *keytype,
+ OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey,
+ const char *input_type,
+ const char *input_struct,
+ const char *keytype, int selection,
OSSL_LIB_CTX *libctx, const char *propquery);
int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
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().
+L<OSSL_DECODER_from_bio(3)>. The caller may use the optional I<input_type>,
+I<input_struct>, I<keytype> and I<selection> to specify what the input is
+expected to contain.
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
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. NULL is valid input and signifies
-that the decoder implementations will find out the input type on their own.
-This is further explained in L<OSSL_DECODER_CTX_set_input_type(3)>.
+The search of decoder implementations can be limited with I<input_type> and
+I<input_struct> which specifies a starting input type and input structure.
+NULL is valid for both of them and signifies that the decoder implementations
+will find out the input type on their own.
+They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and
+L<OSSL_DECODER_CTX_set_input_structure(3)>.
+See L</Input Types> and L</Input Structures> below for further information.
-The search of decoder implementations can also be limited with I<keytype>,
-which specifies the expected resulting keytype. NULL is valid input and
-signifies that the decoder implementations will find out the keytype on
-their own from the input they get.
+The search of decoder implementations can also be limited with I<keytype>
+and I<selection>, which specifies the expected resulting keytype and contents.
+NULL and zero are valid and signify that the decoder implementations will
+find out the keytype and key contents on their own from the input they get.
If no suitable decoder implementation is found,
OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_DECODER_CTX>, but
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).
+=head2 Input Types
+
+Available input types depend on the implementations that available providers
+offer, and provider documentation should have the details.
+
+Among the known input types that OpenSSL decoder implementations offer
+for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>.
+See L<openssl-glossary(7)> for further information on what these input
+types mean.
+
+=head2 Input Structures
+
+Available input structures depend on the implementations that available
+providers offer, and provider documentation should have the details.
+
+Among the known input structures that OpenSSL decoder implementations
+offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>.
+
+OpenSSL decoder implementations also support the input structure
+C<type-specific>. This is the structure used for keys encoded
+according to key type specific specifications. For example, RSA keys
+encoded according to PKCS#1.
+
=head1 RETURN VALUES
OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
--- /dev/null
+=pod
+
+=head1 NAME
+
+openssl-glossary - An OpenSSL Glossary
+
+=head1 DESCRIPTION
+
+=for comment Please keep the items in case-insensitive alphabetical order
+
+=over 4
+
+=item ASN.1, ASN1
+
+ASN.1 ("Abstract Syntax Notation One") is a notation for describing abstract
+types and values. It is defined in the ITU-T documents X.680 to X.683:
+
+L<https://www.itu.int/rec/T-REC-X.680>,
+L<https://www.itu.int/rec/T-REC-X.681>,
+L<https://www.itu.int/rec/T-REC-X.682>,
+L<https://www.itu.int/rec/T-REC-X.683>
+
+=item DER ("Distinguished Encoding Rules")
+
+DER is a binary encoding of data, structured according to an ASN.1
+specification. This is a common encoding used for cryptographic objects
+such as private and public keys, certificates, CRLs, ...
+
+It is defined in ITU-T document X.690:
+
+L<https://www.itu.int/rec/T-REC-X.690>
+
+=item MSBLOB
+
+MSBLOB is a Microsoft specific binary format for RSA and DSA keys, both
+private and public. This form is never passphrase protected.
+
+=item PEM ("Privacy Enhanced Message")
+
+PEM is a format used for encoding of binary content into a mail and ASCII
+friendly form. The content is a series of base64-encoded lines, surrounded
+by begin/end markers each on their own line. For example:
+
+ -----BEGIN PRIVATE KEY-----
+ MIICdg....
+ ... bhTQ==
+ -----END PRIVATE KEY-----
+
+Optional header line(s) may appear after the begin line, and their existence
+depends on the type of object being written or read.
+
+For all OpenSSL uses, the binary content is expected to be a DER encoded
+structure.
+
+This is defined in IETF RFC 1421:
+
+L<https://tools.ietf.org/html/rfc1421>
+
+=item PKCS#8 (also known as "pkcs8" in some parts of OpenSSL)
+
+PKCS#8 is a specification of an ASN.1 structure that OpenSSL uses for
+storing or transmitting any private key in a key type agnostic manner, and
+has both an unencrypted and an encrypted form.
+
+This is specified in RFC 5208:
+
+L<https://tools.ietf.org/html/rfc5208>
+
+=item PVK
+
+PVK is a Microsoft specific binary format for RSA and DSA private keys.
+This form may be passphrase protected.
+
+=item SubjectPublicKeyInfo
+
+SubjectPublicKeyInfo is an ASN.1 structure that OpenSSL uses for storing and
+transmitting any public key in a key type agnostic manner.
+
+This is specified as part of the specification for certificates, RFC 5280:
+
+L<https://tools.ietf.org/html/rfc5280>
+
+=back
+
+=head1 HISTORY
+
+This glossary was 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