From: Richard Levitte Date: Tue, 1 Dec 2020 09:42:53 +0000 (+0100) Subject: DOCS: Update OSSL_DECODER_CTX_new_by_EVP_PKEY.pod to match declarations X-Git-Tag: openssl-3.0.0-alpha10~74 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=19ad83f6c8856b6c28087ff96456b17c471b299a;p=thirdparty%2Fopenssl.git DOCS: Update OSSL_DECODER_CTX_new_by_EVP_PKEY.pod to match declarations Fixes #13441 We're also starting on a glossary, doc/man7/openssl-glossary.pod, where terms we use should be explained. There's no need to explain terms as essays, but at least a few quick lines, and possibly a reference to some external documentation. Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/13581) --- diff --git a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod index 965f19b2e2c..38425ae7dc5 100644 --- a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod +++ b/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod @@ -14,8 +14,10 @@ OSSL_DECODER_CTX_set_passphrase_cb #include 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, @@ -36,7 +38,9 @@ OSSL_DECODER_CTX_set_passphrase_cb OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a B, 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. The caller may use the optional I, +I, I and I to specify what the input is +expected to contain. Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available L implementations, and then builds a list of all potential @@ -44,15 +48,18 @@ decoder implementations that may be able to process the encoded input into data suitable for Bs. All these implementations are implicitly fetched using I and I. -The search of decoder implementations can be limited with I, -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. +The search of decoder implementations can be limited with I and +I 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 and +L. +See L and L below for further information. -The search of decoder implementations can also be limited with I, -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 +and I, 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, but @@ -75,6 +82,29 @@ The internal B 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 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 Bs are C, C, C and C. +See L 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 Bs are C and C. + +OpenSSL decoder implementations also support the input structure +C. 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 diff --git a/doc/man7/openssl-glossary.pod b/doc/man7/openssl-glossary.pod new file mode 100644 index 00000000000..7aa71ea7a55 --- /dev/null +++ b/doc/man7/openssl-glossary.pod @@ -0,0 +1,98 @@ +=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, +L, +L, +L + +=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 + +=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 + +=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 + +=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 + +=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. + +=cut