[openssl] master update
Richard Levitte
levitte at openssl.org
Fri Dec 11 17:51:12 UTC 2020
The branch master has been updated
via 19ad83f6c8856b6c28087ff96456b17c471b299a (commit)
from 05fa5fde10cdacb4899486da0c1a7619dd08bdb7 (commit)
- Log -----------------------------------------------------------------
commit 19ad83f6c8856b6c28087ff96456b17c471b299a
Author: Richard Levitte <levitte at openssl.org>
Date: Tue Dec 1 10:42:53 2020 +0100
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 <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13581)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod | 52 +++++++++++---
doc/man7/openssl-glossary.pod | 98 +++++++++++++++++++++++++++
2 files changed, 139 insertions(+), 11 deletions(-)
create mode 100644 doc/man7/openssl-glossary.pod
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 965f19b2e2..38425ae7dc 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 <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,
@@ -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<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
@@ -44,15 +48,18 @@ 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. 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
@@ -75,6 +82,29 @@ 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).
+=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
diff --git a/doc/man7/openssl-glossary.pod b/doc/man7/openssl-glossary.pod
new file mode 100644
index 0000000000..7aa71ea7a5
--- /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<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
More information about the openssl-commits
mailing list