Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update.

Browse Source
This commit is contained in:
Hakase
2019-09-21 00:43:47 +09:00
parent 2e57f602ae
commit 62515c7d8d
1131 changed files with 47556 additions and 24957 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man7/EVP_KDF-HKDF.pod
+154
View File
@@ -0,0 +1,154 @@
=pod
=head1 NAME
EVP_KDF-HKDF - The HKDF EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
The EVP_KDF-HKDF algorithm implements the HKDF key derivation function.
HKDF follows the "extract-then-expand" paradigm, where the KDF logically
consists of two modules. The first stage takes the input keying material
and "extracts" from it a fixed-length pseudorandom key K. The second stage
"expands" the key K into several additional pseudorandom keys (the output
of the KDF).
=head2 Identity
"HKDF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
The supported parameters are:
=over 4
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
This parameter sets the info value.
The length of the context info buffer cannot exceed 1024 bytes;
this should be more than enough for any normal use of HKDF.
=item B<OSSL_KDF_PARAM_MODE> ("mode") <UTF8 string> or <int>
This parameter sets the mode for the HKDF operation.
There are three modes that are currently defined:
=over 4
=item B<EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND> "EXTRACT_AND_EXPAND"
This is the default mode. Calling L<EVP_KDF-derive(3)> on an EVP_KDF_CTX set
up for HKDF will perform an extract followed by an expand operation in one go.
The derived key returned will be the result after the expand operation. The
intermediate fixed-length pseudorandom key K is not returned.
In this mode the digest, key, salt and info values must be set before a key is
derived otherwise an error will occur.
=item B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY> "EXTRACT_ONLY"
In this mode calling L<EVP_KDF-derive(3)> will just perform the extract
operation. The value returned will be the intermediate fixed-length pseudorandom
key K. The C<keylen> parameter must match the size of K, which can be looked
up by calling EVP_KDF_size() after setting the mode and digest.
The digest, key and salt values must be set before a key is derived otherwise
an error will occur.
=item B<EVP_KDF_HKDF_MODE_EXPAND_ONLY> "EXPAND_ONLY"
In this mode calling L<EVP_KDF-derive(3)> will just perform the expand
operation. The input key should be set to the intermediate fixed-length
pseudorandom key K returned from a previous extract operation.
The digest, key and info values must be set before a key is derived otherwise
an error will occur.
=back
=back
=head1 NOTES
A context for HKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an HKDF expand operation is specified via the C<keylen>
parameter to the L<EVP_KDF-derive(3)> function. When using
EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
the intermediate fixed-length pseudorandom key otherwise an error will occur.
For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
after setting the mode and digest on the C<EVP_KDF_CTX>.
=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret",
salt value "salt" and info value "label":
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[5], *p = params;
kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 5869
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
=head1 COPYRIGHT
Copyright 2016-2019 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
doc/man7/EVP_KDF_PBKDF2.pod → doc/man7/EVP_KDF-PBKDF2.pod
+21 -24
View File
@@ -2,46 +2,45 @@
=head1 NAME
EVP_KDF_PBKDF2 - The PBKDF2 EVP_KDF implementation
EVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF>
API.
The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key
The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key
derivation function, as described in SP800-132; it derives a key from a password
using a salt and iteration count.
=head2 Numeric identity
=head2 Identity
B<EVP_KDF_PBKDF2> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
"PBKDF2" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported controls
=head2 Supported parameters
The supported controls are:
The supported parameters are:
=over 4
=item B<EVP_KDF_CTRL_SET_PASS>
=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
=item B<EVP_KDF_CTRL_SET_SALT>
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
=item B<EVP_KDF_CTRL_SET_ITER>
=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned int>
This control has a default value of 2048.
This parameter has a default value of 2048.
=item B<EVP_KDF_CTRL_SET_MD>
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<EVP_KDF_CTRL_SET_PBKDF2_PKCS5_MODE>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
This control expects one argument: C<int mode>
This control can be used to enable or disable SP800-132 compliance checks.
=item B<OSSL_KDF_PARAM_PKCS5> ("pkcs5") <int>
This parameter can be used to enable or disable SP800-132 compliance checks.
Setting the mode to 0 enables the compliance checks.
The checks performed are:
@@ -59,8 +58,6 @@ The checks performed are:
The default provider uses a default mode of 1 for backwards compatibility,
and the fips provider uses a default mode of 0.
EVP_KDF_ctrl_str() type string: "pkcs5"
The value string is expected to be a decimal number 0 or 1.
=back
@@ -84,16 +81,16 @@ SP800-132
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
L<EVP_KDF(3)/PARAMETERS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
This functionality was added to OpenSSL 3.0.
=head1 COPYRIGHT
doc/man7/EVP_KDF_SCRYPT.pod → doc/man7/EVP_KDF-SCRYPT.pod
+40 -47
View File
@@ -2,14 +2,14 @@
=head1 NAME
EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation
EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
API.
The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key
The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key
derivation function, as described in RFC 7914. It is memory-hard in the sense
that it deliberately requires a significant amount of RAM for efficient
computation. The intention of this is to render brute forcing of passwords on
@@ -32,40 +32,32 @@ GHz), this computation takes about 3 seconds. When N, r or p are not specified,
they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
may be used by scrypt defaults to 1025 MiB.
=head2 Numeric identity
=head2 Identity
B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
"ID-SCRYPT" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported controls
=head2 Supported parameters
The supported controls are:
The supported parameters are:
=over 4
=item B<EVP_KDF_CTRL_SET_PASS>
=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
=item B<EVP_KDF_CTRL_SET_SALT>
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
=item B<OSSL_KDF_PARAM_SCRYPT_N> ("n") <int>
=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
=item B<OSSL_KDF_PARAM_SCRYPT_R> ("r") <int>
=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
=item B<OSSL_KDF_PARAM_SCRYPT_P> ("p") <int>
B<EVP_KDF_CTRL_SET_SCRYPT_N> expects one argument: C<uint64_t N>
B<EVP_KDF_CTRL_SET_SCRYPT_R> expects one argument: C<uint32_t r>
B<EVP_KDF_CTRL_SET_SCRYPT_P> expects one argument: C<uint32_t p>
These controls configure the scrypt work factors N, r and p.
EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively.
The corresponding value strings are expected to be decimal numbers.
These parameters configure the scrypt work factors N, r and p.
N is a parameter of type uint64_t.
Both r and p are parameters of type uint32_t.
=back
@@ -73,35 +65,36 @@ The corresponding value strings are expected to be decimal numbers.
A context for scrypt can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an scrypt key derivation is specified via the
B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
B<keylen> parameter to the L<EVP_KDF-derive(3)> function.
=head1 EXAMPLE
=head1 EXAMPLES
This example derives a 64-byte long test vector using scrypt with the password
"password", salt "NaCl" and N = 1024, r = 8, p = 16.
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[64];
OSSL_PARAM params[6], *p = params;
kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) {
error("EVP_KDF_CTRL_SET_PASS");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_SET_SALT");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) {
error("EVP_KDF_CTRL_SET_SCRYPT_N");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) {
error("EVP_KDF_CTRL_SET_SCRYPT_R");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) {
error("EVP_KDF_CTRL_SET_SCRYPT_P");
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
"password", (size_t)8);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"NaCl", (size_t)4);
*p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024);
*p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
*p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
@@ -130,16 +123,16 @@ RFC 7914
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
L<EVP_KDF(3)/PARAMETERS>
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2019 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
doc/man7/EVP_KDF-SS.pod
+197
View File
@@ -0,0 +1,197 @@
=pod
=head1 NAME
EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF).
SSKDF derives a key using input such as a shared secret key (that was generated
during the execution of a key establishment scheme) and fixedinfo.
SSKDF is also informally referred to as 'Concat KDF'.
=head2 Auxiliary function
The implementation uses a selectable auxiliary function H, which can be one of:
=over 4
=item B<H(x) = hash(x, digest=md)>
=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
=back
Both the HMAC and KMAC implementations set the key using the 'salt' value.
The hash and HMAC also require the digest to be set.
=head2 Identity
"SSKDF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
The supported parameters are:
=over 4
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string>
=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <size_t>
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<EVP_KDF_CTRL_SET_KEY> ("key") <octet string>
This parameter set the shared secret that is used for key derivation.
=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
This parameter sets an optional value for fixedinfo, also known as otherinfo.
=back
=head1 NOTES
A context for SSKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an SSKDF is specified via the C<keylen>
parameter to the L<EVP_KDF-derive(3)> function.
=head1 EXAMPLES
This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
and fixedinfo value "label":
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
fixedinfo value "label" and salt "salt":
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
SN_hmac, strlen(SN_hmac));
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[7], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
SN_kmac128, strlen(SN_kmac128));
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"salt", (size_t)4);
*p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
NIST SP800-56Cr1.
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright
(c) 2019, Oracle and/or its affiliates. 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
doc/man7/EVP_KDF_SSHKDF.pod → doc/man7/EVP_KDF-SSHKDF.pod
+48 -64
View File
@@ -2,69 +2,49 @@
=head1 NAME
EVP_KDF_SSHKDF - The SSHKDF EVP_KDF implementation
EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<SSHKDF> KDF through the B<EVP_KDF> API.
The EVP_KDF_SSHKDF algorithm implements the SSHKDF key derivation function.
The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function.
It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs,
encryption keys and integrity keys.
Five inputs are required to perform key derivation: The hashing function
(for example SHA256), the Initial Key, the Exchange Hash, the Session ID,
and the derivation key type.
=head2 Numeric identity
=head2 Identity
B<EVP_KDF_SSHKDF> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
"SSHKDF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported controls
=head2 Supported parameters
The supported controls are:
The supported parameters are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<EVP_KDF_CTRL_SET_KEY>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
=item B<EVP_KDF_CTRL_SET_SSHKDF_XCGHASH>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<EVP_KDF_CTRL_SET_SSHKDF_SESSION_ID>
=item B<OSSL_KDF_PARAM_SSHKDF_XCGHASH> ("xcghash") <octet string>
These controls expect two arguments: C<unsigned char *buffer>, C<size_t length>
=item B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID> ("session_id") <octet string>
They set the respective values to the first B<length> bytes of the buffer
B<buffer>. If a value is already set, the contents are replaced.
These parameters set the respective values for the KDF.
If a value is already set, the contents are replaced.
EVP_KDF_ctrl_str() takes two type strings for these controls:
=item B<OSSL_KDF_PARAM_SSHKDF_TYPE> ("type") <int>
=over 4
=item "xcghash"
=item "session_id"
The value string is used as is.
=item "hexxcghash"
=item "hexsession_id"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_SSHKDF_TYPE>
This control expects one argument: C<int mode>
Sets the type for the SSHHKDF operation. There are six supported types:
This parameter sets the type for the SSHHKDF operation.
There are six supported types:
=over 4
@@ -100,50 +80,54 @@ A single char of value 70 (ASCII char 'F').
=back
EVP_KDF_ctrl_str() type string: "type"
The value is a string of length one character. The only valid values
are the numerical values of the ASCII characters: "A" (65) to "F" (70).
=back
=head1 NOTES
A context for SSHKDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF);
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of the SSHKDF derivation is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
Since the SSHKDF output length is variable, calling L<EVP_KDF_size()>
parameter to the L<EVP_KDF-derive(3)> function.
Since the SSHKDF output length is variable, calling L<EVP_KDF-size()>
to obtain the requisite length is not meaningful. The caller must
allocate a buffer of the desired length, and pass that buffer to the
L<EVP_KDF_derive(3)> function along with the desired length.
L<EVP_KDF-derive(3)> function along with the desired length.
=head1 EXAMPLE
=head1 EXAMPLES
This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
"xcghash" and "session_id" values:
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char key[1024] = "01234...";
unsigned char xcghash[32] = "012345...";
unsigned char session_id[32] = "012345...";
unsigned char out[8];
size_t outlen = sizeof(out);
kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF);
OSSL_PARAM params[6], *p = params;
if (EVP_KDF_CTX_set_md(kctx, EVP_sha256()) <= 0)
/* Error */
if (EVP_KDF_CTX_set1_key(kctx, key, 1024) <= 0)
/* Error */
if (EVP_KDF_CTX_set1_sshkdf_xcghash(kctx, xcghash, 32) <= 0)
/* Error */
if (EVP_KDF_CTX_set1_sshkdf_session_id(kctx, session_id, 32) <= 0)
/* Error */
if (EVP_KDF_CTX_set_sshkdf_type(kctx,
EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV) <= 0)
kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
key, (size_t)1024);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
xcghash, (size_t)32);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
session_id, (size_t)32);
*p++ = OSSL_PARAM_construct_int(OSSL_KDF_PARAM_SSHKDF_TYPE,
EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
/* Error */
if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
/* Error */
@@ -154,17 +138,17 @@ RFC 4253
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
L<EVP_KDF(3)/PARAMETERS>
=head1 COPYRIGHT
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man7/EVP_KDF-TLS1_PRF.pod
+113
View File
@@ -0,0 +1,113 @@
=pod
=head1 NAME
EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to
and including TLS 1.2.
=head2 Identity
"TLS1-PRF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
The supported parameters are:
=over 4
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
The C<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest
associated with the TLS PRF.
EVP_md5_sha1() is treated as a special case which uses the
PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
=item B<OSSL_KDF_PARAM_SECRET> ("secret") <octet string>
This parameter sets the secret value of the TLS PRF.
Any existing secret value is replaced.
=item B<OSSL_KDF_PARAM_SEED> ("seed") <octet string>
This parameter sets the context seed.
The length of the context seed cannot exceed 1024 bytes;
this should be more than enough for any normal use of the TLS PRF.
=back
=head1 NOTES
A context for the TLS PRF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The digest, secret value and seed must be set before a key is derived otherwise
an error will occur.
The output length of the PRF is specified by the C<keylen> parameter to the
EVP_KDF_derive() function.
=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret"
and seed value "seed":
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
"seed", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 2246, RFC 5246 and NIST SP 800-135 r1
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_KDF-X942.pod
+122
View File
@@ -0,0 +1,122 @@
=pod
=head1 NAME
EVP_KDF-X942 - The X9.42-2001 asn1 EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF-X942 algorithm implements the key derivation function (X942KDF).
X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
derive a key using input such as a shared secret key and other info. The other
info is DER encoded data that contains a 32 bit counter.
=head2 Identity
"X942KDF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
The supported parameters are:
=over 4
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
The shared secret used for key derivation. This parameter sets the secret.
=item B<OSSL_KDF_PARAM_UKM> ("ukm") <octet string>
This parameter is an optional random string that is provided
by the sender called "partyAInfo".
In CMS this is the user keying material.
=item B<OSSL_KDF_PARAM_CEK_ALG> ("cekalg") <UTF8 string>
This parameter sets the CEK wrapping algorithm name.
=back
=head1 NOTES
A context for X942KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF-derive(3)> function.
=head1 EXAMPLES
This example derives 24 bytes, with the secret key "secret" and a random user
keying material:
EVP_KDF_CTX *kctx;
EVP_KDF_CTX *kctx;
unsigned char out[192/8];
unsignred char ukm[64];
OSSL_PARAM params[5], *p = params;
if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
error("RAND_bytes");
kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
if (kctx == NULL)
error("EVP_KDF_fetch");
kctx = EVP_KDF_CTX_new(kdf);
if (kctx == NULL)
error("EVP_KDF_CTX_new");
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm));
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG,
SN_id_smime_alg_CMS3DESwrap,
strlen(SN_id_smime_alg_CMS3DESwrap));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 2631
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/EVP_KDF-X963.pod
+111
View File
@@ -0,0 +1,111 @@
=pod
=head1 NAME
EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF).
X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to
derive a key using input such as a shared secret key and shared info.
=head2 Identity
"X963KDF" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
The supported parameters are:
=over 4
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
The shared secret used for key derivation.
This parameter sets the secret.
=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
This parameter specifies an optional value for shared info.
=back
=head1 NOTES
X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
A context for X963KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an X963KDF is specified via the C<keylen>
parameter to the L<EVP_KDF-derive(3)> function.
=head1 EXAMPLES
This example derives 10 bytes, with the secret key "secret" and sharedinfo
value "label":
EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
"secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
"SEC 1: Elliptic Curve Cryptography"
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/EVP_KDF_HKDF.pod
-180
View File
@@ -1,180 +0,0 @@
=pod
=head1 NAME
EVP_KDF_HKDF - The HKDF EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
The EVP_KDF_HKDF algorithm implements the HKDF key derivation function.
HKDF follows the "extract-then-expand" paradigm, where the KDF logically
consists of two modules. The first stage takes the input keying material
and "extracts" from it a fixed-length pseudorandom key K. The second stage
"expands" the key K into several additional pseudorandom keys (the output
of the KDF).
=head2 Numeric identity
B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_SALT>
=item B<EVP_KDF_CTRL_SET_MD>
=item B<EVP_KDF_CTRL_SET_KEY>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
This control does not expect any arguments.
Resets the context info buffer to zero length.
=item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
Sets the info value to the first B<infolen> bytes of the buffer B<info>. If a
value is already set, the contents of the buffer are appended to the existing
value.
The total length of the context info buffer cannot exceed 1024 bytes;
this should be more than enough for any normal use of HKDF.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "info"
The value string is used as is.
=item "hexinfo"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_HKDF_MODE>
This control expects one argument: C<int mode>
Sets the mode for the HKDF operation. There are three modes that are currently
defined:
=over 4
=item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
This is the default mode. Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set
up for HKDF will perform an extract followed by an expand operation in one go.
The derived key returned will be the result after the expand operation. The
intermediate fixed-length pseudorandom key K is not returned.
In this mode the digest, key, salt and info values must be set before a key is
derived otherwise an error will occur.
=item EVP_KDF_HKDF_MODE_EXTRACT_ONLY
In this mode calling L<EVP_KDF_derive(3)> will just perform the extract
operation. The value returned will be the intermediate fixed-length pseudorandom
key K. The C<keylen> parameter must match the size of K, which can be looked
up by calling EVP_KDF_size() after setting the mode and digest.
The digest, key and salt values must be set before a key is derived otherwise
an error will occur.
=item EVP_KDF_HKDF_MODE_EXPAND_ONLY
In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
operation. The input key should be set to the intermediate fixed-length
pseudorandom key K returned from a previous extract operation.
The digest, key and info values must be set before a key is derived otherwise
an error will occur.
=back
EVP_KDF_ctrl_str() type string: "mode"
The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
or "EXPAND_ONLY".
=back
=head1 NOTES
A context for HKDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
The output length of an HKDF expand operation is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function. When using
EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
the intermediate fixed-length pseudorandom key otherwise an error will occur.
For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
after setting the mode and digest on the C<EVP_KDF_CTX>.
=head1 EXAMPLE
This example derives 10 bytes using SHA-256 with the secret key "secret",
salt value "salt" and info value "label":
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_SET_SALT");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_ADD_HKDF_INFO");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 5869
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2016-2018 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
doc/man7/EVP_KDF_SS.pod
-226
View File
@@ -1,226 +0,0 @@
=pod
=head1 NAME
EVP_KDF_SS - The Single Step / One Step EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF_SS algorithm implements the Single Step key derivation function (SSKDF).
SSKDF derives a key using input such as a shared secret key (that was generated
during the execution of a key establishment scheme) and fixedinfo.
SSKDF is also informally referred to as 'Concat KDF'.
=head2 Auxiliary function
The implementation uses a selectable auxiliary function H, which can be one of:
=over 4
=item B<H(x) = hash(x, digest=md)>
=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
=back
Both the HMAC and KMAC implementations set the key using the 'salt' value.
The hash and HMAC also require the digest to be set.
=head2 Numeric identity
B<EVP_KDF_SS> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
=item B<EVP_KDF_CTRL_SET_MAC>
=item B<EVP_MAC_CTRL_SET_MAC_SIZE>
=item B<EVP_KDF_CTRL_SET_SALT>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<EVP_KDF_CTRL_SET_KEY>
This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
The shared secret used for key derivation. This control sets the secret.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "secret"
The value string is used as is.
=item "hexsecret"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_SSKDF_INFO>
This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "info"
The value string is used as is.
=item "hexinfo"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=back
=head1 NOTES
A context for SSKDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
The output length of an SSKDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
=head1 EXAMPLE
This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
and fixedinfo value "label":
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_SET_SSKDF_INFO");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 EXAMPLE
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
fixedinfo value "label" and salt "salt":
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
error("EVP_KDF_CTRL_SET_MAC");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_SET_SSKDF_INFO");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_SET_SALT");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 EXAMPLE
This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
error("EVP_KDF_CTRL_SET_MAC");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_SET_SSKDF_INFO");
}
/* If not specified the salt will be set to a default value */
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_SET_SALT");
}
/* If not specified the default size will be the size of the derived key */
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
error("EVP_KDF_CTRL_SET_MAC_SIZE");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
NIST SP800-56Cr1.
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright
(c) 2019, Oracle and/or its affiliates. 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
doc/man7/EVP_KDF_TLS1_PRF.pod
-146
View File
@@ -1,146 +0,0 @@
=pod
=head1 NAME
EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation
=head1 DESCRIPTION
Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions up to
and including TLS 1.2.
=head2 Numeric identity
B<EVP_KDF_TLS1_PRF> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
The C<EVP_KDF_CTRL_SET_MD> control is used to set the message digest associated
with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the
PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
=item B<EVP_KDF_CTRL_SET_TLS_SECRET>
This control expects two arguments: C<unsigned char *sec>, C<size_t seclen>
Sets the secret value of the TLS PRF to B<seclen> bytes of the buffer B<sec>.
Any existing secret value is replaced.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "secret"
The value string is used as is.
=item "hexsecret"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_RESET_TLS_SEED>
This control does not expect any arguments.
Resets the context seed buffer to zero length.
=item B<EVP_KDF_CTRL_ADD_TLS_SEED>
This control expects two arguments: C<unsigned char *seed>, C<size_t seedlen>
Sets the seed to B<seedlen> bytes of B<seed>. If a seed is already set it is
appended to the existing value.
The total length of the context seed buffer cannot exceed 1024 bytes;
this should be more than enough for any normal use of the TLS PRF.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "seed"
The value string is used as is.
=item "hexseed"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=back
=head1 NOTES
A context for the TLS PRF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
The digest, secret value and seed must be set before a key is derived otherwise
an error will occur.
The output length of the PRF is specified by the C<keylen> parameter to the
EVP_KDF_derive() function.
=head1 EXAMPLE
This example derives 10 bytes using SHA-256 with the secret key "secret"
and seed value "seed":
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET,
"secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_TLS_SECRET");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_ADD_TLS_SEED");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 2246, RFC 5246 and NIST SP 800-135 r1
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_KDF_X942.pod
-150
View File
@@ -1,150 +0,0 @@
=pod
=head1 NAME
EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
derive a key using input such as a shared secret key and other info. The other
info is DER encoded data that contains a 32 bit counter.
=head2 Numeric identity
B<EVP_KDF_X942> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<EVP_KDF_CTRL_SET_KEY>
This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
The shared secret used for key derivation. This control sets the secret.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "secret"
The value string is used as is.
=item "hexsecret"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_UKM>
This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>
An optional random string that is provided by the sender called "partyAInfo".
In CMS this is the user keying material.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "ukm"
The value string is used as is.
=item "hexukm"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_CEK_ALG>
This control expects one argument: C<char *alg>
The CEK wrapping algorithm name.
EVP_KDF_ctrl_str() type string: "cekalg"
The value string is used as is.
=back
=head1 NOTES
A context for X942KDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
=head1 EXAMPLE
This example derives 24 bytes, with the secret key "secret" and a random user
keying material:
EVP_KDF_CTX *kctx;
unsigned char out[192/8];
unsignred char ukm[64];
if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
error("RAND_bytes");
kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
if (kctx == NULL)
error("EVP_KDF_CTX_new_id");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0)
error("EVP_KDF_CTRL_SET_MD");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0)
error("EVP_KDF_CTRL_SET_KEY");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
error("EVP_KDF_CTRL_SET_UKM");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
SN_id_smime_alg_CMS3DESwrap) <= 0)
error("EVP_KDF_CTRL_SET_CEK_ALG");
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 2631
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/EVP_KDF_X963.pod
-136
View File
@@ -1,136 +0,0 @@
=pod
=head1 NAME
EVP_KDF_X963 - The X9.63-2001 EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF_X963 algorithm implements the key derivation function (X963KDF).
X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to
derive a key using input such as a shared secret key and shared info.
=head2 Numeric identity
B<EVP_KDF_X963> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<EVP_KDF_CTRL_SET_KEY>
This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
The shared secret used for key derivation. This control sets the secret.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "secret"
The value string is used as is.
=item "hexsecret"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_SHARED_INFO>
This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
An optional value for shared info. This control sets the shared info.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "info"
The value string is used as is.
=item "hexinfo"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=back
=head1 NOTES
X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
A context for X963KDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
The output length of an X963KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
=head1 EXAMPLE
This example derives 10 bytes, with the secret key "secret" and sharedinfo
value "label":
EVP_KDF_CTX *kctx;
unsigned char out[10];
kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SHARED_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_SET_SHARED_INFO");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
"SEC 1: Elliptic Curve Cryptography"
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/EVP_MAC-BLAKE2.pod
+79
View File
@@ -0,0 +1,79 @@
=pod
=head1 NAME
EVP_MAC-BLAKE2, EVP_MAC-BLAKE2BMAC, EVP_MAC-BLAKE2SMAC
- The BLAKE2 EVP_MAC implementations
=head1 DESCRIPTION
Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
=head2 Identity
These implementations are identified with one of these names and
properties, to be used with EVP_MAC_fetch():
=over 4
=item "BLAKE2BMAC", "default=yes"
=item "BLAKE2SMAC", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and
at least 1 byte in both cases.
=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
BLAKE2SMAC.
It is empty by default.
=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
BLAKE2SMAC.
It is empty by default.
=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
When set, this can be any number between between 1 and 32 for
EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
It is 32 and 64 respectively by default.
=back
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 HISTORY
The macros and functions described here were added to OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-CMAC.pod
+66
View File
@@ -0,0 +1,66 @@
=pod
=head1 NAME
EVP_MAC-CMAC - The CMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing CMAC MACs through the B<EVP_MAC> API.
=head2 Identity
This implementation is identified with this name and properties, to be
used with EVP_MAC_fetch():
=over 4
=item "CMAC", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
=over 4
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
=back
The "size" parameter can also be retrieved with with EVP_MAC_size().
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-GMAC.pod
+68
View File
@@ -0,0 +1,68 @@
=pod
=head1 NAME
EVP_MAC-GMAC - The GMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing GMAC MACs through the B<EVP_MAC> API.
=head2 Identity
This implementation is identified with this name and properties, to be
used with EVP_MAC_fetch():
=over 4
=item "GMAC", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
=over 4
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
=back
The "size" parameter can also be retrieved with EVP_MAC_size().
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-HMAC.pod
+70
View File
@@ -0,0 +1,70 @@
=pod
=head1 NAME
EVP_MAC-HMAC - The HMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing HMAC MACs through the B<EVP_MAC> API.
=head2 Identity
This implementation is identified with this name and properties, to be
used with EVP_MAC_fetch():
=over 4
=item "HMAC", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <octet string>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <utf8 string>
=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
=back
The "flags" parameter is passed directly to HMAC_CTX_set_flags().
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
=over 4
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
=back
The "size" parameter can also be retrieved with EVP_MAC_size().
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>, L<HMAC(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-KMAC.pod
+64
View File
@@ -0,0 +1,64 @@
=pod
=head1 NAME
EVP_MAC-KMAC, EVP_MAC-KMAC256, EVP_MAC-KMAC256
- The KMAC EVP_MAC implementations
=head1 DESCRIPTION
Support for computing KMAC MACs through the B<EVP_MAC> API.
=head2 Identity
These implementations are identified with one of these names and
properties, to be used with EVP_MAC_fetch():
=over 4
=item "KMAC128", "default=yes"
=item "KMAC256", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
=item B<OSSL_MAC_PARAM_XOF>
=back
The "xof" parameter value is exptect to be 1 or 0. Use 1 to enable XOF
mode. If XOF is enabled then the output len that is encoded as part of
the input stream is set to zero.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-Poly1305.pod
+60
View File
@@ -0,0 +1,60 @@
=pod
=head1 NAME
EVP_MAC-Poly1305 - The Poly1305 EVP_MAC implementation
=head1 DESCRIPTION
Support for computing Poly1305 MACs through the B<EVP_MAC> API.
=head2 Identity
This implementation is identified with this name and properties, to be
used with EVP_MAC_fetch():
=over 4
=item "Poly1305", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
=over 4
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
=back
The "size" parameter can also be retrieved with with EVP_MAC_size().
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC-Siphash.pod
+54
View File
@@ -0,0 +1,54 @@
=pod
=head1 NAME
EVP_MAC-Siphash - The SipHash EVP_MAC implementation
=head1 DESCRIPTION
Support for computing SipHash MACs through the B<EVP_MAC> API.
=head2 Identity
This implementation is identified with this name and properties, to be
used with EVP_MAC_fetch():
=over 4
=item "Siphash", "default=yes"
=back
=head2 Supported parameters
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
=back
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
Copyright 2018-2019 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
doc/man7/EVP_MAC_BLAKE2.pod
-114
View File
@@ -1,114 +0,0 @@
=pod
=head1 NAME
EVP_MAC_BLAKE2 - The BLAKE2 EVP_MAC implementation
=head1 DESCRIPTION
Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_BLAKE2B> and B<EVP_MAC_BLAKE2S> are the numeric identities for this
implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
This is a string value of at most 64 bytes for EVP_MAC_BLAKE2B
or 32 for EVP_MAC_BLAKE2S and at least 1 byte in both cases.
This must be set before calling EVP_MAC_init().
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_CUSTOM>
This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
If used this must be set before calling EVP_MAC_init().
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "custom"
The value string is used as is.
=item "hexcustom"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_SALT>
This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
If used this must be set before calling EVP_MAC_init().
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "salt"
The value string is used as is.
=item "hexsalt"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_SIZE>
EVP_MAC_ctrl_str() type string: "outlen"
This is an optional value string containing a decimal number between 1 and
32 for EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
If it is not set it uses the default digest size of 32 and 64 respectively.
If used this must be set before calling EVP_MAC_init().
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 HISTORY
The macros and functions described here were added to OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_CMAC.pod
-65
View File
@@ -1,65 +0,0 @@
=pod
=head1 NAME
EVP_MAC_CMAC - The CMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing CMAC MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_CMAC> is the numeric identity for this implementation, and
can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_ENGINE>
=item B<EVP_MAC_CTRL_SET_CIPHER>
These work as described in L<EVP_MAC(3)/CONTROLS>.
EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
The value is expected to be the name of a cipher.
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_GMAC.pod
-83
View File
@@ -1,83 +0,0 @@
=pod
=head1 NAME
EVP_MAC_GMAC - The GMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing GMAC MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_GMAC> is the numeric identity for this implementation, and
can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_IV>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "iv"
The value string is used as is.
=item "hexiv"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_ENGINE>
=item B<EVP_MAC_CTRL_SET_CIPHER>
These work as described in L<EVP_MAC(3)/CONTROLS> with the restriction that the
cipher must be an AEAD one.
EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
The value is expected to be the name of a cipher.
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_HMAC.pod
-71
View File
@@ -1,71 +0,0 @@
=pod
=head1 NAME
EVP_MAC_HMAC - The HMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing HMAC MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_HMAC> is the numeric identity for this implementation, and
can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_FLAGS>
Sets HMAC flags. This is passed directly to HMAC_CTX_set_flags().
There are no corresponding string control types.
=item B<EVP_MAC_CTRL_SET_ENGINE>
=item B<EVP_MAC_CTRL_SET_MD>
These work as described in L<EVP_MAC(3)/CONTROLS>.
EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_MD>: "digest"
The value is expected to be the name of a cipher.
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_KMAC.pod
-94
View File
@@ -1,94 +0,0 @@
=pod
=head1 NAME
EVP_MAC_KMAC - The KMAC EVP_MAC implementation
=head1 DESCRIPTION
Support for computing KMAC MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_KMAC128> and B<EVP_MAC_KMAC256> are the numeric identities for this
implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
This must be set before calling EVP_MAC_init().
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_CUSTOM>
This is an optional string value that can be set before calling EVP_MAC_init().
If it is not set it uses the default value "".
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "custom"
The value string is used as is.
=item "hexcustom"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=item B<EVP_MAC_CTRL_SET_SIZE>
EVP_MAC_ctrl_str() type string: "outlen"
This is an optional value string containing a decimal number. If it is not set
it uses the default value of 32 for EVP_MAC_KMAC128 and 64 for EVP_MAC_KMAC256.
This can be called any time before EVP_MAC_final().
=item B<EVP_MAC_CTRL_SET_XOF>
EVP_MAC_ctrl_str() type string: "xof"
The value string is expected to be an integer value of 1 or 0. Use 1 to enable
XOF mode. If XOF is enabled then the output len that is encoded as part of the
input stream is set to zero.
This can be called any time before EVP_MAC_final().
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_POLY1305.pod
-55
View File
@@ -1,55 +0,0 @@
=pod
=head1 NAME
EVP_MAC_POLY1305 - The Poly1305 EVP_MAC implementation
=head1 DESCRIPTION
Support for computing Poly1305 MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_POLY1305> is the numeric identity for this implementation,
and can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/EVP_MAC_SIPHASH.pod
-61
View File
@@ -1,61 +0,0 @@
=pod
=head1 NAME
EVP_MAC_SIPHASH - The SipHash EVP_MAC implementation
=head1 DESCRIPTION
Support for computing SipHash MACs through the B<EVP_MAC> API.
=head2 Numeric identity
B<EVP_MAC_SIPHASH> is the numeric identity for this implementation,
and can be used in functions like EVP_MAC_CTX_new_id() and
EVP_get_macbynid().
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_MAC_CTRL_SET_SIZE>
EVP_MAC_ctrl_str() type string: "digestsize"
The value string is expected to contain a decimal number.
=item B<EVP_MAC_CTRL_SET_KEY>
EVP_MAC_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
The value string is expected to be a hexadecimal number, which will be
decoded before passing on as control value.
=back
=back
=head1 SEE ALSO
L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
=head1 COPYRIGHT
Copyright 2018 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
doc/man7/Ed25519.pod
+1 -1
View File
@@ -53,7 +53,7 @@ Ed25519 and Ed448 can be tested within L<speed(1)> application since version 1.1
Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
specified, then both Ed25519 and Ed448 are benchmarked.
=head1 EXAMPLE
=head1 EXAMPLES
This example generates an B<ED25519> private key and writes it to standard
output in PEM format:
doc/man7/RAND_DRBG.pod
+1 -1
View File
@@ -209,7 +209,7 @@ The last feature has been added to support the common practice used with
previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
=head2 Entropy Input vs. Additional Data
=head2 Entropy Input and Additional Data
The DRBG distinguishes two different types of random input: I<entropy>,
which comes from a trusted source, and I<additional input>',
doc/man7/SM2.pod
+1 -1
View File
@@ -41,7 +41,7 @@ done by calling:
And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit()
or EVP_DigestVerifyInit() in such a scenario.
=head1 EXAMPLE
=head1 EXAMPLES
This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify
a message with the SM2 signature algorithm and the SM3 hash algorithm:
doc/man7/X25519.pod
+1 -1
View File
@@ -37,7 +37,7 @@ X25519 or X448 public keys can be set directly using
L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
=head1 EXAMPLE
=head1 EXAMPLES
This example generates an B<X25519> private key and writes it to standard
output in PEM format:
doc/man7/bio.pod
+1 -1
View File
@@ -52,7 +52,7 @@ pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 EXAMPLE
=head1 EXAMPLES
Create a memory BIO:
doc/man7/openssl-core.h.pod
+2 -2
View File
@@ -69,8 +69,8 @@ It's normally passed in arrays, where the array is terminated with an
element where all fields are zero (for non-pointers) or C<NULL> (for
pointers).
These arrays can be used both to set parameters for some object, and
to request parameters.
These arrays can be used to set parameters for some object, to request
parameters, and to describe parameters.
C<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
doc/man7/openssl_user_macros.pod.in
+1 -1
View File
@@ -60,7 +60,7 @@ However, it is recommended to start using the second form instead:
=item C<m>
This form is a simple number that represents the major version number
and is supported for version 3.0.0 and up. For extra convenience,
and is supported for version 3.0 and up. For extra convenience,
these numbers are also available:
=over 4
doc/man7/provider-base.pod
+493
View File
@@ -0,0 +1,493 @@
=pod
=head1 NAME
provider-base
- The basic OpenSSL library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
#include <openssl/core_numbers.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Functions offered by libcrypto to the providers */
const OSSL_ITEM *core_gettable_params(const OSSL_PROVIDER *prov);
int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
int core_thread_start(const OSSL_PROVIDER *prov,
OSSL_thread_stop_handler_fn handfn);
OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
void core_new_error(const OSSL_PROVIDER *prov);
void core_set_error_debug(const OSSL_PROVIDER *prov,
const char *file, int line, const char *func);
void core_vset_error(const OSSL_PROVIDER *prov,
uint32_t reason, const char *fmt, va_list args);
/*
* Some OpenSSL functionality is directly offered to providers via
* dispatch
*/
void *CRYPTO_malloc(size_t num, const char *file, int line);
void *CRYPTO_zalloc(size_t num, const char *file, int line);
void *CRYPTO_memdup(const void *str, size_t siz,
const char *file, int line);
char *CRYPTO_strdup(const char *str, const char *file, int line);
char *CRYPTO_strndup(const char *str, size_t s,
const char *file, int line);
void CRYPTO_free(void *ptr, const char *file, int line);
void CRYPTO_clear_free(void *ptr, size_t num,
const char *file, int line);
void *CRYPTO_realloc(void *addr, size_t num,
const char *file, int line);
void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
const char *file, int line);
void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
void CRYPTO_secure_free(void *ptr, const char *file, int line);
void CRYPTO_secure_clear_free(void *ptr, size_t num,
const char *file, int line);
int CRYPTO_secure_allocated(const void *ptr);
void OPENSSL_cleanse(void *ptr, size_t len);
unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
/* Functions offered by the provider to libcrypto */
void provider_teardown(void *provctx);
const OSSL_ITEM *provider_gettable_params(void *provctx);
int provider_get_params(void *provctx, OSSL_PARAM params[]);
const OSSL_ALGORITHM *provider_query_operation(void *provctx,
int operation_id,
const int *no_store);
const OSSL_ITEM *provider_get_reason_strings(void *provctx);
=head1 DESCRIPTION
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays, in the call
of the provider initialization function. See L<provider(7)/Provider>
for a description of the initialization function.
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" core_gettable_params() has these:
typedef OSSL_ITEM *
(OSSL_core_gettable_params_fn)(const OSSL_PROVIDER *prov);
static ossl_inline OSSL_NAME_core_gettable_params_fn
OSSL_get_core_gettable_params(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
provider):
core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS
core_get_params OSSL_FUNC_CORE_GET_PARAMS
core_thread_start OSSL_FUNC_CORE_THREAD_START
core_get_library_context OSSL_FUNC_CORE_GET_LIBRARY_CONTEXT
core_new_error OSSL_FUNC_CORE_NEW_ERROR
core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG
core_set_error OSSL_FUNC_CORE_SET_ERROR
CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC
CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC
CRYPTO_memdup OSSL_FUNC_CRYPTO_MEMDUP
CRYPTO_strdup OSSL_FUNC_CRYPTO_STRDUP
CRYPTO_strndup OSSL_FUNC_CRYPTO_STRNDUP
CRYPTO_free OSSL_FUNC_CRYPTO_FREE
CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE
CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC
CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC
CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC
CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC
CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE
CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
BIO_new_file OSSL_FUNC_BIO_NEW_FILE
BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF
BIO_read_ex OSSL_FUNC_BIO_READ_EX
BIO_free OSSL_FUNC_BIO_FREE
OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF
For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
F<libcrypto>):
provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN
provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS
provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION
provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
=head2 Core functions
core_gettable_params() returns a constant array of descriptor
B<OSSL_PARAM>, for parameters that core_get_params() can handle.
core_get_params() retrieves I<prov> parameters from the core.
See L</Core parameters> below for a description of currently known
parameters.
=for comment core_thread_start() TBA
core_get_library_context() retrieves the library context in which the
B<OSSL_PROVIDER> object I<prov> is stored.
This may sometimes be useful if the provider wishes to store a
reference to its context in the same library context.
core_new_error(), core_set_error_debug() and core_set_error() are
building blocks for reporting an error back to the core, with
reference to the provider object I<prov>.
=over 4
=item core_new_error()
allocates a new thread specific error record.
This corresponds to the OpenSSL function L<ERR_new(3)>.
=item core_set_error_debug()
sets debugging information in the current thread specific error
record.
The debugging information includes the name of the file I<file>, the
line I<line> and the function name I<func> where the error occured.
This corresponds to the OpenSSL function L<ERR_set_debug(3)>.
=item core_set_error()
sets the I<reason> for the error, along with any addition data.
The I<reason> is a number defined by the provider and used to index
the reason strings table that's returned by
provider_get_reason_strings().
The additional data is given as a format string I<fmt> and a set of
arguments I<args>, which are treated in the same manner as with
BIO_vsnprintf().
I<file> and I<line> may also be passed to indicate exactly where the
error occured or was reported.
This corresponds to the OpenSSL function L<ERR_vset_error(3)>.
=back
CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(),
OPENSSL_cleanse(), and OPENSSL_hexstr2buf() correspond exactly to the
public functions with the same name.
As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
direct pointers to those public functions.
=head2 Provider functions
provider_teardown() is called when a provider is shut down and removed
from the core's provider store.
It must free the passed I<provctx>.
provider_gettable_params() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
can handle.
provider_get_params() should process the B<OSSL_PARAM> array
I<params>, setting the values of the parameters it understands.
provider_query_operation() should return a constant B<OSSL_ALGORITHM>
that corresponds to the given I<operation_id>.
It should indicate if the core may store a reference to this array by
setting I<*no_store> to 0 (core may store a reference) or 1 (core may
not store a reference).
provider_get_reason_strings() should return a constant B<OSSL_ITEM>
array that provides reason strings for reason codes the provider may
use when reporting errors using core_put_error().
None of these functions are mandatory, but a provider is fairly
useless without at least provider_query_operation(), and
provider_gettable_params() is fairly useless if not accompanied by
provider_get_params().
=head2 Core parameters
core_get_params() understands the following known parameters:
=over 4
=item "openssl-version"
This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
OpenSSL libraries' full version string, i.e. the string expanded from
the macro B<OPENSSL_VERSION_STR>.
=item "provider-name"
This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
OpenSSL libraries' idea of what the calling provider is called.
=back
Additionally, provider specific configuration parameters from the
config file are available, in dotted name form.
The dotted name form is a concatenation of section names and final
config command name separated by periods.
For example, let's say we have the following config example:
openssl_conf = openssl_init
[openssl_init]
providers = providers_sect
[providers_sect]
foo = foo_sect
[foo_sect]
activate = 1
data1 = 2
data2 = str
more = foo_more
[foo_more]
data3 = foo,bar
The provider will have these additional parameters available:
=over 4
=item "activate"
pointing at the string "1"
=item "data1"
pointing at the string "2"
=item "data2"
pointing at the string "str"
=item "more.data3"
pointing at the string "foo,bar"
=back
For more information on handling parameters, see L<OSSL_PARAM(3)> as
L<OSSL_PARAM_int(3)>.
=head1 EXAMPLES
This is an example of a simple provider made available as a
dynamically loadable module.
It implements the fictitious algorithm C<FOO> for the fictitious
operation C<BAR>.
#include <malloc.h>
#include <openssl/core.h>
#include <openssl/core_numbers.h>
/* Errors used in this provider */
#define E_MALLOC 1
static const OSSL_ITEM reasons[] = {
{ E_MALLOC, "memory allocation failure" }.
{ 0, NULL } /* Termination */
};
/*
* To ensure we get the function signature right, forward declare
* them using function types provided by openssl/core_numbers.h
*/
OSSL_OP_bar_newctx_fn foo_newctx;
OSSL_OP_bar_freectx_fn foo_freectx;
OSSL_OP_bar_init_fn foo_init;
OSSL_OP_bar_update_fn foo_update;
OSSL_OP_bar_final_fn foo_final;
OSSL_provider_query_operation_fn p_query;
OSSL_provider_get_reason_strings_fn p_reasons;
OSSL_provider_teardown_fn p_teardown;
OSSL_provider_init_fn OSSL_provider_init;
OSSL_core_put_error *c_put_error = NULL;
/* Provider context */
struct prov_ctx_st {
OSSL_PROVIDER *prov;
}
/* operation context for the algorithm FOO */
struct foo_ctx_st {
struct prov_ctx_st *provctx;
int b;
};
static void *foo_newctx(void *provctx)
{
struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
if (fooctx != NULL)
fooctx->provctx = provctx;
else
c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
return fooctx;
}
static void foo_freectx(void *fooctx)
{
free(fooctx);
}
static int foo_init(void *vfooctx)
{
struct foo_ctx_st *fooctx = vfooctx;
fooctx->b = 0x33;
}
static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
{
struct foo_ctx_st *fooctx = vfooctx;
/* did you expect something serious? */
if (inl == 0)
return 1;
for (; inl-- > 0; in++)
*in ^= fooctx->b;
return 1;
}
static int foo_final(void *vfooctx)
{
struct foo_ctx_st *fooctx = vfooctx;
fooctx->b = 0x66;
}
static const OSSL_DISPATCH foo_fns[] = {
{ OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
{ OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
{ OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
{ OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
{ OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
{ 0, NULL }
};
static const OSSL_ALGORITHM bars[] = {
{ "FOO", "provider=chumbawamba", foo_fns },
{ NULL, NULL, NULL }
};
static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
int *no_store)
{
switch (operation_id) {
case OSSL_OP_BAR:
return bars;
}
return NULL;
}
static const OSSL_ITEM *p_reasons(void *provctx)
{
return reasons;
}
static void p_teardown(void *provctx)
{
free(provctx);
}
static const OSSL_DISPATCH prov_fns[] = {
{ OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
{ OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
{ OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
{ 0, NULL }
};
int OSSL_provider_init(const OSSL_PROVIDER *provider,
const OSSL_DISPATCH *in,
const OSSL_DISPATCH **out,
void **provctx)
{
struct prov_ctx_st *pctx = NULL;
for (; in->function_id != 0; in++)
switch (in->function_id) {
case OSSL_FUNC_CORE_PUT_ERROR:
c_put_error = OSSL_get_core_put_error(in);
break;
}
*out = prov_fns;
if ((pctx = malloc(sizeof(*pctx))) == NULL) {
/*
* ALEA IACTA EST, if the core retrieves the reason table
* regardless, that string will be displayed, otherwise not.
*/
c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
return 0;
}
return 1;
}
This relies on a few things existing in F<openssl/core_numbers.h>:
#define OSSL_OP_BAR 4711
#define OSSL_FUNC_BAR_NEWCTX 1
typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
{ return (OSSL_OP_bar_newctx_fn *)opf->function; }
#define OSSL_FUNC_BAR_FREECTX 2
typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
{ return (OSSL_OP_bar_freectx_fn *)opf->function; }
#define OSSL_FUNC_BAR_INIT 3
typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
{ return (OSSL_OP_bar_init_fn *)opf->function; }
#define OSSL_FUNC_BAR_UPDATE 4
typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
unsigned char *in, size_t inl);
static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
{ return (OSSL_OP_bar_update_fn *)opf->function; }
#define OSSL_FUNC_BAR_FINAL 5
typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
{ return (OSSL_OP_bar_final_fn *)opf->function; }
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The concept of providers and everything surrounding them was
introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-cipher.pod
+349
View File
@@ -0,0 +1,349 @@
=pod
=head1 NAME
provider-cipher - The cipher library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Context management */
void *OP_cipher_newctx(void *provctx);
void OP_cipher_freectx(void *cctx);
void *OP_cipher_dupctx(void *cctx);
/* Encryption/decryption */
int OP_cipher_encrypt_init(void *cctx, const unsigned char *key,
size_t keylen, const unsigned char *iv,
size_t ivlen);
int OP_cipher_decrypt_init(void *cctx, const unsigned char *key,
size_t keylen, const unsigned char *iv,
size_t ivlen);
int OP_cipher_update(void *cctx, unsigned char *out, size_t *outl,
size_t outsize, const unsigned char *in, size_t inl);
int OP_cipher_final(void *cctx, unsigned char *out, size_t *outl,
size_t outsize);
int OP_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
size_t outsize, const unsigned char *in, size_t inl);
/* Cipher parameter descriptors */
const OSSL_PARAM *OP_cipher_gettable_params(void);
/* Cipher operation parameter descriptors */
const OSSL_PARAM *OP_cipher_gettable_ctx_params(void);
const OSSL_PARAM *OP_cipher_settable_ctx_params(void);
/* Cipher parameters */
int OP_cipher_get_params(OSSL_PARAM params[]);
/* Cipher operation parameters */
int OP_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
int OP_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);
=head1 DESCRIPTION
This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.
The CIPHER operation enables providers to implement cipher algorithms and make
them available to applications via the API functions L<EVP_EncryptInit_ex(3)>,
L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> (as well as the decrypt
equivalents and other related functions).
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_cipher_newctx() has these:
typedef void *(OSSL_OP_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_OP_cipher_newctx_fn
OSSL_get_OP_cipher_newctx(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX
OP_cipher_freectx OSSL_FUNC_CIPHER_FREECTX
OP_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX
OP_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT
OP_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT
OP_cipher_update OSSL_FUNC_CIPHER_UPDATE
OP_cipher_final OSSL_FUNC_CIPHER_FINAL
OP_cipher_cipher OSSL_FUNC_CIPHER_CIPHER
OP_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS
OP_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS
OP_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS
OP_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS
OP_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
OP_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS
A cipher algorithm implementation may not implement all of these functions.
In order to be a consistent set of functions there must at least be a complete
set of "encrypt" functions, or a complete set of "decrypt" functions, or a
single "cipher" function.
In all cases both the OP_cipher_newctx and OP_cipher_freectx functions must be
present.
All other functions are optional.
=head2 Context Management Functions
OP_cipher_newctx() should create and return a pointer to a provider side
structure for holding context information during a cipher operation.
A pointer to this context will be passed back in a number of the other cipher
operation function calls.
The parameter B<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_cipher_freectx() is passed a pointer to the provider side cipher context in
the B<cctx> parameter.
This function should free any resources associated with that context.
OP_cipher_dupctx() should duplicate the provider side cipher context in the
B<cctx> parameter and return the duplicate copy.
=head2 Encryption/Decryption Functions
OP_cipher_encrypt_init() initialises a cipher operation for encryption given a
newly created provider side cipher context in the B<cctx> parameter.
The key to be used is given in B<key> which is B<keylen> bytes long.
The IV to be used is given in B<iv> which is B<ivlen> bytes long.
OP_cipher_decrypt_init() is the same as OP_cipher_encrypt_init() except that it
initialises the context for a decryption operation.
OP_cipher_update() is called to supply data to be encrypted/decrypted as part of
a previously initialised cipher operation.
The B<cctx> parameter contains a pointer to a previously initialised provider
side context.
OP_cipher_update() should encrypt/decrypt B<inl> bytes of data at the location
pointed to by B<in>.
The encrypted data should be stored in B<out> and the amount of data written to
B<*outl> which should not exceed B<outsize> bytes.
OP_cipher_update() may be called multiple times for a single cipher operation.
It is the responsibility of the cipher implementation to handle input lengths
that are not multiples of the block length.
In such cases a cipher implementation will typically cache partial blocks of
input data until a complete block is obtained.
B<out> may be the same location as B<in> but it should not partially overlap.
The same expectations apply to B<outsize> as documented for
L<EVP_EncryptUpdate(3)> and L<EVP_DecryptUpdate(3)>.
OP_cipher_final() completes an encryption or decryption started through previous
OP_cipher_encrypt_init() or OP_cipher_decrypt_init(), and OP_cipher_update()
calls.
The B<cctx> parameter contains a pointer to the provider side context.
Any final encryption/decryption output should be written to B<out> and the
amount of data written to B<*outl> which should not exceed B<outsize> bytes.
The same expectations apply to B<outsize> as documented for
L<EVP_EncryptFinal(3)> and L<EVP_DecryptFinal(3)>.
OP_cipher_cipher() performs encryption/decryption using the provider side cipher
context in the B<cctx> parameter that should have been previously initialised via
a call to OP_cipher_encrypt_init() or OP_cipher_decrypt_init.
This should call the raw underlying cipher function without any padding.
This will be invoked in the provider as a result of the application calling
L<EVP_Cipher(3)>.
The application is responsible for ensuring that the input is a multiple of the
block length.
The data to be encrypted/decrypted will be in B<in>, and it will be B<inl> bytes
in length.
The output from the encryption/decryption should be stored in B<out> and the
amount of data stored should be put in B<*outl> which should be no more than
B<outsize> bytes.
=head2 Cipher Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
these functions.
OP_cipher_get_params() gets details of the algorithm implementation
and stores them in B<params>.
OP_cipher_set_ctx_params() sets cipher operation parameters for the
provider side cipher context B<cctx> to B<params>.
Any parameter settings are additional to any that were previously set.
OP_cipher_get_ctx_params() gets cipher operation details details from
the given provider side cipher context B<cctx> and stores them in B<params>.
OP_cipher_gettable_params(), OP_cipher_gettable_ctx_params(), and
OP_cipher_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
as descriptors of the parameters that OP_cipher_get_params(),
OP_cipher_get_ctx_params(), and OP_cipher_set_ctx_params() can handle,
respectively.
Parameters currently recognised by built-in ciphers are as follows. Not all
parameters are relevant to, or are understood by all ciphers:
=over 4
=item B<OSSL_CIPHER_PARAM_PADDING> (uint)
Sets the padding mode for the associated cipher ctx.
Setting a value of 1 will turn padding on.
Setting a value of 0 will turn padding off.
=item B<OSSL_CIPHER_PARAM_MODE> (uint)
Gets the mode for the associated cipher algorithm.
See L<EVP_CIPHER_mode(3)> for a list of valid modes.
=item B<OSSL_CIPHER_PARAM_BLOCK_SIZE> (size_t)
Gets the block size for the associated cipher algorithm.
The block size should be 1 for stream ciphers.
Note that the block size for a cipher may be different to the block size for
the underlying encryption/decryption primitive.
For example AES in CTR mode has a block size of 1 (because it operates like a
stream cipher), even though AES has a block size of 16.
=item B<OSSL_CIPHER_PARAM_FLAGS> (ulong)
Gets any flags for the associated cipher algorithm.
See L<EVP_CIPHER_meth_set_flags(3)> for a list of currently defined cipher
flags.
=item B<OSSL_CIPHER_PARAM_KEYLEN> (size_t)
Gets the key length for the associated cipher algorithm.
This can also be used to get or set the key length for the associated cipher
ctx.
=item B<OSSL_CIPHER_PARAM_IVLEN> (size_t)
Gets the IV length for the associated cipher algorithm.
=item B<OSSL_CIPHER_PARAM_IV> (octet_string OR octet_ptr)
Gets the IV for the associated cipher ctx.
=item B<OSSL_CIPHER_PARAM_NUM> (uint)
Gets or sets the cipher specific "num" parameter for the associated cipher ctx.
Built-in ciphers typically use this to track how much of the current underlying
block has been "used" already.
=item B<OSSL_CIPHER_PARAM_AEAD_TAG> (octet_string)
Gets or sets the AEAD tag for the associated cipher ctx.
See L<EVP_EncryptInit(3)/AEAD Interface>.
=item B<OSSL_CIPHER_PARAM_AEAD_TAGLEN> (size_t)
Gets the tag length to be used for an AEAD cipher for the associated cipher ctx.
It returns a default value if it has not been set.
=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD> (octet_string)
=for comment TODO(3.0): Consider changing this interface so that all ciphers
use the standard AEAD interface - rather than having this special purpose
interface for TLS
Sets TLSv1.2 AAD information for the associated cipher ctx.
TLSv1.2 AAD information is always 13 bytes in length and is as defined for the
"additional_data" field described in section 6.2.3.3 of RFC5246.
=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD> (size_t)
Gets the length of the tag that will be added to a TLS record for the AEAD
tag for the associated cipher ctx.
=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED> (octet_string)
=for comment TODO(3.0): This interface needs completely redesigning!
Sets the fixed portion of an IV for an AEAD cipher used in a TLS record
encryption/ decryption for the associated cipher ctx.
TLS record encryption/decryption always occurs "in place" so that the input and
output buffers are always the same memory location.
AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part
that varies with every record.
Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records.
TLS records are encrypted/decrypted using a single OP_cipher_cipher call per
record.
For a record decryption the first bytes of the input buffer will be the explict
part of the IV and the final bytes of the input buffer will be the AEAD tag.
The length of the explicit part of the IV and the tag length will depend on the
cipher in use and will be defined in the RFC for the relevant ciphersuite.
In order to allow for "in place" decryption the plaintext output should be
written to the same location in the output buffer that the ciphertext payload
was read from, i.e. immediately after the explicit IV.
When encrypting a record the first bytes of the input buffer will be empty to
allow space for the explicit IV, as will the final bytes where the tag will
be written.
The length of the input buffer will include the length of the explicit IV, the
payload, and the tag bytes.
The cipher implementation should generate the explicit IV and write it to the
beginning of the output buffer, do "in place" encryption of the payload and
write that to the output buffer, and finally add the tag onto the end of the
output buffer.
Whether encrypting or decrypting the value written to B<*outl> in the
OP_cipher_cipher call should be the length of the payload excluding the explicit
IV length and the tag length.
=item B<OSSL_CIPHER_PARAM_AEAD_IVLEN> (size_t)
Sets the IV length to be used for an AEAD cipher for the associated cipher ctx.
=item B<OSSL_CIPHER_PARAM_RANDOM_KEY> (octet_string)
Gets a implementation specific randomly generated key for the associated
cipher ctx. This is currently only supported by 3DES (which sets the key to
odd parity).
=back
=head1 RETURN VALUES
OP_cipher_newctx() and OP_cipher_dupctx() should return the newly created
provider side cipher context, or NULL on failure.
OP_cipher_encrypt_init(), OP_cipher_decrypt_init(), OP_cipher_update(),
OP_cipher_final(), OP_cipher_cipher(), OP_cipher_get_params(),
OP_cipher_get_ctx_params() and OP_cipher_set_ctx_params() should return 1 for
success or 0 on error.
OP_cipher_gettable_params(), OP_cipher_gettable_ctx_params() and
OP_cipher_settable_ctx_params() should return a constant B<OSSL_PARAM>
array, or NULL if none is offered.
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The provider CIPHER interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-digest.pod
+293
View File
@@ -0,0 +1,293 @@
=pod
=head1 NAME
provider-digest - The digest library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/*
* Digests support the following function signatures in OSSL_DISPATCH arrays.
* (The function signatures are not actual functions).
*/
/* Context management */
void *OP_digest_newctx(void *provctx);
void OP_digest_freectx(void *dctx);
void *OP_digest_dupctx(void *dctx);
/* Digest generation */
int OP_digest_init(void *dctx);
int OP_digest_update(void *dctx, const unsigned char *in, size_t inl);
int OP_digest_final(void *dctx, unsigned char *out, size_t *outl,
size_t outsz);
int OP_digest_digest(void *provctx, const unsigned char *in, size_t inl,
unsigned char *out, size_t *outl, size_t outsz);
/* Digest parameter descriptors */
const OSSL_PARAM *OP_cipher_gettable_params(void);
/* Digest operation parameter descriptors */
const OSSL_PARAM *OP_cipher_gettable_ctx_params(void);
const OSSL_PARAM *OP_cipher_settable_ctx_params(void);
/* Digest parameters */
int OP_digest_get_params(OSSL_PARAM params[]);
/* Digest operation parameters */
int OP_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
int OP_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);
=head1 DESCRIPTION
This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.
The DIGEST operation enables providers to implement digest algorithms and make
them available to applications via the API functions L<EVP_DigestInit_ex(3)>,
L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal(3)> (and other related functions).
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_digest_newctx() has these:
typedef void *(OSSL_OP_digest_newctx_fn)(void *provctx);
static ossl_inline OSSL_OP_digest_newctx_fn
OSSL_get_OP_digest_newctx(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
OP_digest_freectx OSSL_FUNC_DIGEST_FREECTX
OP_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
OP_digest_init OSSL_FUNC_DIGEST_INIT
OP_digest_update OSSL_FUNC_DIGEST_UPDATE
OP_digest_final OSSL_FUNC_DIGEST_FINAL
OP_digest_digest OSSL_FUNC_DIGEST_DIGEST
OP_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS
OP_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS
OP_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS
OP_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS
OP_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
OP_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS
A digest algorithm implementation may not implement all of these functions.
In order to be usable all or none of OP_digest_newctx, OP_digest_freectx,
OP_digest_init, OP_digest_update and OP_digest_final should be implemented.
All other functions are optional.
=head2 Context Management Functions
OP_digest_newctx() should create and return a pointer to a provider side
structure for holding context information during a digest operation.
A pointer to this context will be passed back in a number of the other digest
operation function calls.
The parameter B<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_digest_freectx() is passed a pointer to the provider side digest context in
the B<dctx> parameter.
This function should free any resources associated with that context.
OP_digest_dupctx() should duplicate the provider side digest context in the
B<dctx> parameter and return the duplicate copy.
=head2 Digest Generation Functions
OP_digest_init() initialises a digest operation given a newly created
provider side digest context in the B<dctx> parameter.
OP_digest_update() is called to supply data to be digested as part of a
previously initialised digest operation.
The B<dctx> parameter contains a pointer to a previously initialised provider
side context.
OP_digest_update() should digest B<inl> bytes of data at the location pointed to
by B<in>.
OP_digest_update() may be called multiple times for a single digest operation.
OP_digest_final() generates a digest started through previous OP_digest_init()
and OP_digest_update() calls.
The B<dctx> parameter contains a pointer to the provider side context.
The digest should be written to B<*out> and the length of the digest to
B<*outl>.
The digest should not exceed B<outsz> bytes.
OP_digest_digest() is a "oneshot" digest function.
No provider side digest context is used.
Instead the provider context that was created during provider initialisation is
passed in the B<provctx> parameter (see L<provider(3)>).
B<inl> bytes at B<in> should be digested and the result should be stored at
B<out>. The length of the digest should be stored in B<*outl> which should not
exceed B<outsz> bytes.
=head2 Digest Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
these functions.
OP_digest_get_params() gets details of the algorithm implementation
and stores them in B<params>.
OP_digest_set_ctx_params() sets digest operation parameters for the
provider side digest context B<dctx> to B<params>.
Any parameter settings are additional to any that were previously set.
OP_digest_get_ctx_params() gets digest operation details details from
the given provider side digest context B<dctx> and stores them in B<params>.
OP_digest_gettable_params(), OP_digest_gettable_ctx_params(), and
OP_digest_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
as descriptors of the parameters that OP_digest_get_params(),
OP_digest_get_ctx_params(), and OP_digest_set_ctx_params() can handle,
respectively.
Parameters currently recognised by built-in digests with this function
are as follows. Not all parameters are relevant to, or are understood
by all digests:
=over 4
=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (size_t)
The digest block size.
=item B<OSSL_DIGEST_PARAM_SIZE> (size_t)
The digest output size.
=item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long)
Diverse flags that describe exceptional behaviour for the digest:
=over 4
=item B<EVP_MD_FLAG_ONESHOT>
This digest method can only handle one block of input.
=item B<EVP_MD_FLAG_XOF>
This digest method is an extensible-output function (XOF) and supports
setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter.
=item B<EVP_MD_FLAG_DIGALGID_NULL>
When setting up a DigestAlgorithmIdentifier, this flag will have the
parameter set to NULL by default. Use this for PKCS#1. I<Note: if
combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
=item B<EVP_MD_FLAG_DIGALGID_ABSENT>
When setting up a DigestAlgorithmIdentifier, this flag will have the
parameter be left absent by default. I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
=item B<EVP_MD_FLAG_DIGALGID_CUSTOM>
Custom DigestAlgorithmIdentifier handling via ctrl, with
B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
Currently unused.
=back
=back
=head2 Digest Context Parameters
OP_digest_set_ctx_params() sets digest parameters associated with the
given provider side digest context B<dctx> to B<params>.
Any parameter settings are additional to any that were previously set.
See L<OSSL_PARAM(3)> for further details on the parameters structure.
OP_digest_get_ctx_params() gets details of currently set parameters
values associated with the give provider side digest context B<dctx>
and stores them in B<params>.
See L<OSSL_PARAM(3)> for further details on the parameters structure.
Parameters currently recognised by built-in digests are as follows. Not all
parameters are relevant to, or are understood by all digests:
=over 4
=item B<OSSL_DIGEST_PARAM_XOFLEN> (size_t)
Sets the digest length for extendable output functions.
=item B<OSSL_DIGEST_PARAM_SSL3_MS> (octet string)
This parameter is set by libssl in order to calculate a signature hash for an
SSLv3 CertificateVerify message as per RFC6101.
It is only set after all handshake messages have already been digested via
OP_digest_update() calls.
The parameter provides the master secret value to be added to the digest.
The digest implementation should calculate the complete digest as per RFC6101
section 5.6.8.
The next call after setting this parameter will be OP_digest_final().
This is only relevant for implementations of SHA1 or MD5_SHA1.
=item B<OSSL_DIGEST_PARAM_PAD_TYPE> (uint)
Sets the pad type to be used.
The only built-in digest that uses this is MDC2.
Normally the final MDC2 block is padded with 0s.
If the pad type is set to 2 then the final block is padded with 0x80 followed by
0s.
=item B<OSSL_DIGEST_PARAM_MICALG> (utf8 string)
Gets the digest Message Integrity Check algorithm string.
This is used when creating S/MIME multipart/signed messages, as specified in
RFC 5751.
=back
=head1 RETURN VALUES
OP_digest_newctx() and OP_digest_dupctx() should return the newly created
provider side digest context, or NULL on failure.
OP_digest_init(), OP_digest_update(), OP_digest_final(), OP_digest_digest(),
OP_digest_set_params() and OP_digest_get_params() should return 1 for success or
0 on error.
OP_digest_size() should return the digest size.
OP_digest_block_size() should return the block size of the underlying digest
algorithm.
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The provider DIGEST interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-keyexch.pod
+185
View File
@@ -0,0 +1,185 @@
=pod
=head1 NAME
provider-keyexch - The keyexch library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Context management */
void *OP_keyexch_newctx(void *provctx);
void OP_keyexch_freectx(void *ctx);
void *OP_keyexch_dupctx(void *ctx);
/* Shared secret derivation */
int OP_keyexch_init(void *ctx, void *provkey);
int OP_keyexch_set_peer(void *ctx, void *provkey);
int OP_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
size_t outlen);
/* Key Exchange parameters */
int OP_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OP_keyexch_settable_ctx_params(void);
=head1 DESCRIPTION
This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.
The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key
exchange algorithms and make them available to applications via the API
functions L<EVP_PKEY_derive_init_ex(3)>, and L<EVP_PKEY_derive(3)> (as well as
other related functions).
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_keyexch_newctx() has these:
typedef void *(OSSL_OP_keyexch_newctx_fn)(void *provctx);
static ossl_inline OSSL_OP_keyexch_newctx_fn
OSSL_get_OP_keyexch_newctx(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX
OP_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX
OP_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX
OP_keyexch_init OSSL_FUNC_KEYEXCH_INIT
OP_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER
OP_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE
OP_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
OP_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
A key exchange algorithm implementation may not implement all of these functions.
In order to be a consistent set of functions a provider must implement
OP_keyexch_newctx, OP_keyexch_freectx, OP_keyexch_init and OP_keyexch_derive.
All other functions are optional.
A key exchange algorithm must also implement some mechanism for generating,
loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
See L<provider-keymgmt(7)> for further details.
=head2 Context Management Functions
OP_keyexch_newctx() should create and return a pointer to a provider side
structure for holding context information during a key exchange operation.
A pointer to this context will be passed back in a number of the other key
exchange operation function calls.
The paramater B<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_keyexch_freectx() is passed a pointer to the provider side key exchange
context in the B<ctx> parameter.
This function should free any resources associated with that context.
OP_keyexch_dupctx() should duplicate the provider side key exchange context in
the B<ctx> parameter and return the duplicate copy.
=head2 Shared Secret Derivation Functions
OP_keyexch_init() initialises a key exchange operation given a provider side key
exchange context in the B<ctx> paramter, and a pointer to a provider key object
in the B<provkey> parameter. The key object should have been previously
generated, loaded or imported into the provider using the key management
(OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
OP_keyexch_set_peer() is called to supply the peer's public key (in the
B<provkey> parameter) to be used when deriving the shared secret.
It is also passed a previously initialised key exchange context in the B<ctx>
parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.
OP_keyexch_derive() performs the actual key exchange itself by deriving a shared
secret.
A previously initialised key exchange context is passed in the B<ctx>
parameter.
The derived secret should be written to the location B<secret> which should not
exceed B<outlen> bytes.
The length of the shared secret should be written to B<*secretlen>.
If B<secret> is NULL then the maximum length of the shared secret should be
written to B<*secretlen>.
=head2 Key Exchange Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
the OP_keyexch_set_params() function.
OP_keyexch_set_ctx_params() sets key exchange parameters associated with the
given provider side key exchange context B<ctx> to B<params>.
Any parameter settings are additional to any that were previously set.
Parameters currently recognised by built-in key exchange algorithms are as
follows.
Not all parameters are relevant to, or are understood by all key exchange
algorithms:
=over 4
=item B<OSSL_EXCHANGE_PARAM_PAD> (uint)
Sets the padding mode for the associated key exchange ctx.
Setting a value of 1 will turn padding on.
Setting a vlue of 0 will turn padding off.
If padding is off then the derived shared secret may be smaller than the largest
possible secret size.
If padding is on then the derived shared secret will have its first bytes filled
with 0s where necessary to make the shared secret the same size as the largest
possible secret size.
=back
OP_keyexch_settable_ctx_params() gets a constant B<OSSL_PARAM> array that
decribes the settable parameters, i.e. parameters that can be used with
OP_signature_set_ctx_params().
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head1 RETURN VALUES
OP_keyexch_newctx() and OP_keyexch_dupctx() should return the newly created
provider side key exchange context, or NULL on failure.
OP_keyexch_init(), OP_keyexch_set_peer(), OP_keyexch_derive() and
OP_keyexch_set_params() should return 1 for success or 0 on error.
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The provider KEYEXCH interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-keymgmt.pod
+178
View File
@@ -0,0 +1,178 @@
=pod
=head1 NAME
provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
#include <openssl/core_numbers.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Key domain parameter creation and destruction */
void *OP_keymgmt_importdomparams(void *provctx, const OSSL_PARAM params[]);
void *OP_keymgmt_gendomparams(void *provctx, const OSSL_PARAM params[]);
void OP_keymgmt_freedomparams(void *domparams);
/* Key domain parameter export */
int OP_keymgmt_exportdomparams(void *domparams, OSSL_PARAM params[]);
/* Key domain parameter discovery */
const OSSL_PARAM *OP_keymgmt_importdomparam_types(void);
const OSSL_PARAM *OP_keymgmt_exportdomparam_types(void);
/* Key creation and destruction */
void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]);
void *OP_keymgmt_genkey(void *provctx,
void *domparams, const OSSL_PARAM genkeyparams[]);
void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen);
void OP_keymgmt_freekey(void *key);
/* Key export */
int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]);
/* Key discovery */
const OSSL_PARAM *OP_keymgmt_importkey_types(void);
const OSSL_PARAM *OP_keymgmt_exportkey_types(void);
=head1 DESCRIPTION
The KEYMGMT operation doesn't have much public visibility in OpenSSL
libraries, it's rather an internal operation that's designed to work
in tandem with operations that use private/public key pairs.
Because the KEYMGMT operation shares knowledge with the operations it
works with in tandem, they must belong to the same provider.
The OpenSSL libraries will ensure that they do.
The primary responsibility of the KEYMGMT operation is to hold the
provider side domain parameters and keys for the OpenSSL library
EVP_PKEY structure.
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_keymgmt_importdomparams() has these:
typedef void *
(OSSL_OP_keymgmt_importdomparams_fn)(void *provctx,
const OSSL_PARAM params[]);
static ossl_inline OSSL_OP_keymgmt_importdomparams_fn
OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_keymgmt_importdomparams OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS
OP_keymgmt_gendomparams OSSL_FUNC_KEYMGMT_GENDOMPARAMS
OP_keymgmt_freedomparams OSSL_FUNC_KEYMGMT_FREEDOMPARAMS
OP_keymgmt_exportdomparams OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS
OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES
OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES
OP_keymgmt_importkey OSSL_FUNC_KEYMGMT_IMPORTKEY
OP_keymgmt_genkey OSSL_FUNC_KEYMGMT_GENKEY
OP_keymgmt_loadkey OSSL_FUNC_KEYMGMT_LOADKEY
OP_keymgmt_freekey OSSL_FUNC_KEYMGMT_FREEKEY
OP_keymgmt_exportkey OSSL_FUNC_KEYMGMT_EXPORTKEY
OP_keymgmt_importkey_types OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES
OP_keymgmt_exportkey_types OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES
=head2 Domain Parameter Functions
OP_keymgmt_importdomparams() should create a provider side structure
for domain parameters, with values taken from the passed B<OSSL_PARAM>
array I<params>.
OP_keymgmt_gendomparams() should generate domain parameters and create
a provider side structure for them.
Values of the passed B<OSSL_PARAM> array I<params> should be used as
input for parameter generation.
OP_keymgmt_freedomparams() should free the passed provider side domain
parameter structure I<domparams>.
OP_keymgmt_exportdomparams() should extract values from the passed
provider side domain parameter structure I<domparams> into the passed
B<OSSL_PARAM> I<params>.
Only the values specified in I<params> should be extracted.
OP_keymgmt_importdomparam_types() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams()
can handle.
=for comment There should be one corresponding to OP_keymgmt_gendomparams()
as well...
OP_keymgmt_exportdomparam_types() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that can be exported with
OP_keymgmt_exportdomparams().
=head2 Key functions
OP_keymgmt_importkey() should create a provider side structure
for keys, with values taken from the passed B<OSSL_PARAM> array
I<params>.
OP_keymgmt_genkey() should generate keys and create a provider side
structure for them.
Values from the passed domain parameters I<domparams> as well as from
the passed B<OSSL_PARAM> array I<params> should be used as input for
key generation.
OP_keymgmt_loadkey() should return a provider side key structure with
a key loaded from a location known only to the provider, identitified
with the identity I<id> of size I<idlen>.
This identity is internal to the provider and is retrieved from the
provider through other means.
=for comment Right now, OP_keymgmt_loadkey is useless, but will be
useful as soon as we have a OSSL_STORE interface
OP_keymgmt_freekey() should free the passed I<key>.
OP_keymgmt_exportkey() should extract values from the passed
provider side key I<key> into the passed B<OSSL_PARAM> I<params>.
Only the values specified in I<params> should be extracted.
OP_keymgmt_importkey_types() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey()
can handle.
=for comment There should be one corresponding to OP_keymgmt_genkey()
as well...
OP_keymgmt_exportkey_types() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that can be exported with
OP_keymgmt_exportkeys().
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The KEYMGMT interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-mac.pod
+244
View File
@@ -0,0 +1,244 @@
=pod
=head1 NAME
provider-mac - The mac library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Context management */
void *OP_mac_newctx(void *provctx);
void OP_mac_freectx(void *mctx);
void *OP_mac_dupctx(void *src);
/* Encryption/decryption */
int OP_mac_init(void *mctx);
int OP_mac_update(void *mctx, const unsigned char *in, size_t inl);
int OP_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize);
/* MAC parameter descriptors */
const OSSL_PARAM *OP_mac_get_params(void);
const OSSL_PARAM *OP_mac_get_ctx_params(void);
const OSSL_PARAM *OP_mac_set_ctx_params(void);
/* MAC parameters */
int OP_mac_get_params(OSSL_PARAM params[]);
int OP_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]);
int OP_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);
=head1 DESCRIPTION
This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.
The MAC operation enables providers to implement mac algorithms and make
them available to applications via the API functions L<EVP_MAC_init(3)>,
L<EVP_MACM_update(3)> and L<EVP_MAC_final(3)>.
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_mac_newctx() has these:
typedef void *(OSSL_OP_mac_newctx_fn)(void *provctx);
static ossl_inline OSSL_OP_mac_newctx_fn
OSSL_get_OP_mac_newctx(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_mac_newctx OSSL_FUNC_MAC_NEWCTX
OP_mac_freectx OSSL_FUNC_MAC_FREECTX
OP_mac_dupctx OSSL_FUNC_MAC_DUPCTX
OP_mac_init OSSL_FUNC_MAC_INIT
OP_mac_update OSSL_FUNC_MAC_UPDATE
OP_mac_final OSSL_FUNC_MAC_FINAL
OP_mac_get_params OSSL_FUNC_MAC_GET_PARAMS
OP_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS
OP_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS
OP_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS
OP_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS
OP_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS
A mac algorithm implementation may not implement all of these functions.
In order to be a consistent set of functions, at least the following functions
must be implemented: OP_mac_newctx(), OP_mac_freectx(), OP_mac_init(),
OP_mac_update(), OP_mac_final().
All other functions are optional.
=head2 Context Management Functions
OP_mac_newctx() should create and return a pointer to a provider side
structure for holding context information during a mac operation.
A pointer to this context will be passed back in a number of the other mac
operation function calls.
The paramater I<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_mac_freectx() is passed a pointer to the provider side mac context in
the I<mctx> parameter.
If it receives NULL as I<mctx> value, it should not do anything other than
return.
This function should free any resources associated with that context.
OP_mac_dupctx() should duplicate the provider side mac context in the
I<mctx> parameter and return the duplicate copy.
=head2 Encryption/Decryption Functions
OP_mac_init() initialises a mac operation given a newly created provider
side mac context in the I<mctx> paramter.
OP_mac_update() is called to supply data for MAC computation of a previously
initialised mac operation.
The I<mctx> parameter contains a pointer to a previously initialised provider
side context.
OP_mac_update() may be called multiple times for a single mac operation.
OP_mac_final() completes the MAC computation started through previous
OP_mac_init() and OP_mac_update() calls.
The I<mctx> parameter contains a pointer to the provider side context.
The resulting MAC should be written to I<out> and the amount of data written
to I<*outl>, which should not exceed I<outsize> bytes.
The same expectations apply to I<outsize> as documented for
L<EVP_MAC_final(3)>.
=head2 Mac Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
these functions.
OP_mac_get_params() gets details of parameter values associated with the
provider algorithm and stores them in I<params>.
OP_mac_set_ctx_params() sets mac parameters associated with the given
provider side mac context I<mctx> to I<params>.
Any parameter settings are additional to any that were previously set.
OP_mac_get_ctx_params() gets details of currently set parameter values
associated with the given provider side mac context I<mctx> and stores them
in I<params>.
OP_mac_gettable_params(), OP_mac_gettable_ctx_params(), and
OP_mac_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
as descriptors of the parameters that OP_mac_get_params(),
OP_mac_get_ctx_params(), and OP_mac_set_ctx_params() can handle,
respectively.
Parameters currently recognised by built-in macs are as follows. Not all
parameters are relevant to, or are understood by all macs:
=over 4
=item B<OSSL_MAC_PARAM_KEY> (octet string)
Sets the key in the associated MAC ctx.
=item B<OSSL_MAC_PARAM_IV> (octet string)
Sets the IV of the underlying cipher, when applicable.
=item B<OSSL_MAC_PARAM_CUSTOM> (utf8 string)
Sets the custom string in the associated MAC ctx.
=item B<OSSL_MAC_PARAM_SALT> (octet string)
Sets the salt of the underlying cipher, when applicable.
=item B<OSSL_MAC_PARAM_BLOCK_XOF> (int)
Sets XOF mode in the associated MAC ctx.
0 means no XOF mode, 1 means XOF mode.
=item B<OSSL_MAC_PARAM_FLAGS> (int)
Gets flags associated with the MAC.
=for comment We need to investigate if this is the right approach
=item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
=item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
Sets the name of the underlying cipher or digest to be used.
It must name a suitable algorithm for the MAC that's being used.
=item B<OSSL_MAC_PARAM_ENGINE> (utf8 string)
Sets the name of an engine that implements the underlying algorithm.
This must be given together with the algorithm naming parameter to be
considered valid.
=item B<OSSL_MAC_PARAM_PROPERTIES> (utf8 string)
Sets the properties to be queried when trying to fetch the underlying algorithm.
This must be given together with the algorithm naming parameter to be
considered valid.
Note that both this and B<OSSL_MAC_PARAM_ENGINE> can be given at the same time.
If the underlying algorithm ends up being fetched from a provider, offered by
and engine, or a built in legacy function depends on what is available.
=item B<OSSL_MAC_PARAM_SIZE> (int)
Can be used to get the resulting MAC size.
With some MAC algorithms, it can also be used to set the size that the
resulting MAC should have.
Allowable sizes are decided within each implementation.
=back
=head1 RETURN VALUES
OP_mac_newctx() and OP_mac_dupctx() should return the newly created
provider side mac context, or NULL on failure.
OP_mac_init(), OP_mac_update(), OP_mac_final(), OP_mac_get_params(),
OP_mac_get_ctx_params() and OP_mac_set_ctx_params() should return 1 for
success or 0 on error.
OP_mac_gettable_params(), OP_mac_gettable_ctx_params() and
OP_mac_settable_ctx_params() should return a constant B<OSSL_PARAM>
array, or NULL if none is offered.
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The provider MAC interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider-signature.pod
+239
View File
@@ -0,0 +1,239 @@
=pod
=head1 NAME
provider-signature - The signature library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Context management */
void *OP_signature_newctx(void *provctx);
void OP_signature_freectx(void *ctx);
void *OP_signature_dupctx(void *ctx);
/* Signing */
int OP_signature_sign_init(void *ctx, void *provkey);
int OP_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
size_t sigsize, const unsigned char *tbs, size_t tbslen);
/* Verifying */
int OP_signature_verify_init(void *ctx, void *provkey);
int OP_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
const unsigned char *tbs, size_t tbslen);
/* Verify Recover */
int OP_signature_verify_recover_init(void *ctx, void *provkey);
int OP_signature_verify_recover(void *ctx, unsigned char *rout,
size_t *routlen, size_t routsize,
const unsigned char *sig, size_t siglen);
/* Signature parameters */
int OP_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OP_signature_gettable_ctx_params(void);
int OP_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OP_signature_settable_ctx_params(void);
=head1 DESCRIPTION
This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.
The signature (OSSL_OP_SIGNATURE) operation enables providers to implement
signature algorithms and make them available to applications via the API
functions L<EVP_PKEY_sign_init_ex(3)>, L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify_init_ex(3)>, L<EVP_PKEY_verify(3)>,
L<EVP_PKEY_verify_recover_init_ex(3)> and L<EVP_PKEY_verify_recover(3)> (as well
as other related functions).
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_get_{name}>.
For example, the "function" OP_signature_newctx() has these:
typedef void *(OSSL_OP_signature_newctx_fn)(void *provctx);
static ossl_inline OSSL_OP_signature_newctx_fn
OSSL_get_OP_signature_newctx(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
OP_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX
OP_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX
OP_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX
OP_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT
OP_signature_sign OSSL_FUNC_SIGNATURE_SIGN
OP_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT
OP_signature_verify OSSL_FUNC_SIGNATURE_VERIFY
OP_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
OP_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
OP_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
OP_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
OP_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
OP_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
A signature algorithm implementation may not implement all of these functions.
In order to be a consistent set of functions a provider must implement
OP_signature_newctx and OP_signature_freectx.
It must also implement both of OP_signature_sign_init and OP_signature_sign,
or both of OP_signature_verify_init and OP_signature_verify, or both of
OP_signature_verify_recover_init and OP_signature_verify_recover.
All other functions are optional.
A signature algorithm must also implement some mechanism for generating,
loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
See L<provider-keymgmt(7)> for further details.
=head2 Context Management Functions
OP_signature_newctx() should create and return a pointer to a provider side
structure for holding context information during a signature operation.
A pointer to this context will be passed back in a number of the other signature
operation function calls.
The parameter B<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_signature_freectx() is passed a pointer to the provider side signature
context in the B<ctx> parameter.
This function should free any resources associated with that context.
OP_signature_dupctx() should duplicate the provider side signature context in
the B<ctx> parameter and return the duplicate copy.
=head2 Signing Functions
OP_signature_sign_init() initialises a context for signing given a provider side
signature context in the B<ctx> parameter, and a pointer to a provider key object
in the B<provkey> parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.
OP_signature_sign() performs the actual signing itself.
A previously initialised signature context is passed in the B<ctx>
parameter.
The data to be signed is pointed to be the B<tbs> parameter which is B<tbslen>
bytes long.
Unless B<sig> is NULL, the signature should be written to the location pointed
to by the B<sig> parameter and it should not exceed B<sigsize> bytes in length.
The length of the signature should be written to B<*siglen>.
If B<sig> is NULL then the maximum length of the signature should be written to
B<*siglen>.
=head2 Verify Functions
OP_signature_verify_init() initialises a context for verifying a signature given
a provider side signature context in the B<ctx> parameter, and a pointer to a
provider key object in the B<provkey> parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.
OP_signature_verify() performs the actual verification itself.
A previously initialised signature context is passed in the B<ctx> parameter.
The data that the signature covers is pointed to be the B<tbs> parameter which
is B<tbslen> bytes long.
The signature is pointed to by the B<sig> parameter which is B<siglen> bytes
long.
=head2 Verify Recover Functions
OP_signature_verify_recover_init() initialises a context for recovering the
signed data given a provider side signature context in the B<ctx> parameter, and
a pointer to a provider key object in the B<provkey> parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.
OP_signature_verify_recover() performs the actual verify recover itself.
A previously initialised signature context is passed in the B<ctx> parameter.
The signature is pointed to by the B<sig> parameter which is B<siglen> bytes
long.
Unless B<rout> is NULL, the recovered data should be written to the location
pointed to by B<rout> which should not exceed B<routsize> bytes in length.
The length of the recovered data should be written to B<*routlen>.
If B<rout> is B<NULL> then the maximum size of the output buffer is written to
the B<routlen> parameter.
=head2 Signature Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions.
OP_signature_get_ctx_params() gets signature parameters associated with the
given provider side signature context B<ctx> and stored them in B<params>.
OP_signature_set_ctx_params() sets the signature parameters associated with the
given provider side signature context B<ctx> to B<params>.
Any parameter settings are additional to any that were previously set.
Parameters currently recognised by built-in signature algorithms are as
follows.
Not all parameters are relevant to, or are understood by all signature
algorithms:
=over 4
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string>
Get or sets the name of the digest algorithm used for the input to the signature
functions.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t>
Gets or sets the output size of the digest algorithm used for the input to the
signature functions.
=back
OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a
constant B<OSSL_PARAM> array that decribes the gettable and settable parameters,
i.e. parameters that can be used with OP_signature_get_ctx_params() and
OP_signature_set_ctx_params() respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head1 RETURN VALUES
OP_signature_newctx() and OP_signature_dupctx() should return the newly created
provider side signature, or NULL on failure.
All other functions should return 1 for success or 0 on error.
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The provider SIGNATURE interface was introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/provider.pod
+401
View File
@@ -0,0 +1,401 @@
=pod
=head1 NAME
provider - OpenSSL operation implementation providers
=head1 SYNOPSIS
=for comment generic
#include <openssl/provider.h>
=head1 DESCRIPTION
=head2 General
A I<provider>, in OpenSSL terms, is a unit of code that provides one
or more implementations for various operations for diverse algorithms
that one might want to perform.
An I<operation> is something one wants to do, such as encryption and
decryption, key derivation, MAC calculation, signing and verification,
etc.
An I<algorithm> is a named method to perform an operation.
Very often, the algorithms revolve around cryptographic operations,
but may also revolve around other types of operation, such as managing
certain types of objects.
=head2 Provider
I<NOTE: This section is mostly interesting for provider authors.>
A I<provider> offers an initialization function, as a set of base
functions in the form of an B<OSSL_DISPATCH> array, and by extension,
a set of B<OSSL_ALGORITHM>s (see L<openssl-core.h(7)>).
It may be a dynamically loadable module, or may be built-in, in
OpenSSL libraries or in the application.
If it's a dynamically loadable module, the initialization function
must be named C<OSSL_provider_init> and must be exported.
If it's built-in, the initialization function may have any name.
The initialization function must have the following signature:
int NAME(const OSSL_PROVIDER *provider,
const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
void **provctx);
I<provider> is the OpenSSL library object for the provider, and works
as a handle for everything the OpenSSL libraries need to know about
the provider.
For the provider itself, it may hold some interesting information,
and is also passed to some of the functions given in the dispatch
array I<in>.
I<in> is a dispatch array of base functions offered by the OpenSSL
libraries, and the available functions are further described in
L<provider-base(7)>.
I<*out> must be assigned a dispatch array of base functions that the
provider offers to the OpenSSL libraries.
The functions that may be offered are further described in
L<provider-base(7)>, and they are the central means of communication
between the OpenSSL libraries and the provider.
I<*provctx> should be assigned a provider specific context to allow
the provider multiple simultaneous uses.
This pointer will be passed to various operation functions offered by
the provider.
One of the functions the provider offers to the OpenSSL libraries is
the central mechanism for the OpenSSL libraries to get access to
operation implementations for diverse algorithms.
Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION>
and has the following signature:
const OSSL_ALGORITHM *provider_query_operation(void *provctx,
int operation_id,
const int *no_store);
I<provctx> is the provider specific context that was passed back by
the initialization function.
I<operation_id> is an operation identity (see L</Operations> below).
I<no_store> is a flag back to the OpenSSL libraries which, when
non-zero, signifies that the OpenSSL libraries will not store a
reference to the returned data in their internal store of
implementations.
The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL
library API that uses providers for their implementation, most
commonly in the I<fetching> type of functions
(see L</Fetching algorithms> below).
=head2 Operations
I<NOTE: This section is mostly interesting for provider authors.>
Operations are referred to with numbers, via macros with names
starting with C<OSSL_OP_>.
With each operation comes a set of defined function types that a
provider may or may not offer, depending on its needs.
Currently available operations are:
=over 4
=item Digests
In the OpenSSL libraries, the corresponding method object is
B<EVP_MD>.
The number for this operation is B<OSSL_OP_DIGEST>.
The functions the provider can offer are described in
L<provider-digest(7)>
=item Symmetric ciphers
In the OpenSSL libraries, the corresponding method object is
B<EVP_CIPHER>.
The number for this operation is B<OSSL_OP_CIPHER>.
The functions the provider can offer are described in
L<provider-cipher(7)>
=begin comment NOT AVAILABLE YET
=item Message Authentication Code (MAC)
In the OpenSSL libraries, the corresponding method object is
B<EVP_MAC>.
The number for this operation is B<OSSL_OP_MAC>.
The functions the provider can offer are described in
L<provider-mac(7)>
=end comment
=begin comment NOT AVAILABLE YET
=item Key Derivation Function (KDF)
In the OpenSSL libraries, the corresponding method object is
B<EVP_KDF>.
The number for this operation is B<OSSL_OP_KDF>.
The functions the provider can offer are described in
L<provider-kdf(7)>
=end comment
=item Key Exchange
In the OpenSSL libraries, the corresponding method object is
B<EVP_KEYEXCh>.
The number for this operation is B<OSSL_OP_KEYEXCH>.
The functions the provider can offer are described in
L<provider-keyexch(7)>
=back
=head2 Fetching algorithms
=head3 Explicit fetch
I<NOTE: This section is mostly interesting to OpenSSL users.>
Users of the OpenSSL libraries never query the provider directly for
its diverse implementations and dispatch tables.
Instead, the diverse OpenSSL APIs often have fetching functions that
do the work, and they return an appropriate method object back to the
user.
These functions usually have the name C<APINAME_fetch>, where
C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>.
These fetching functions follow a fairly common pattern, where three
arguments are passed:
=over 4
=item The library context
See L<OPENSSL_CTX(3)> for a more detailed description.
This may be NULL to signify the default (global) library context, or a
context created by the user.
Only providers loaded in this library context (see
L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
function.
=item An identifier
This is most commonly an algorithm name (this is the case for all EVP
methods), but may also be called something else.
=for comment For example, an OSSL_STORE implementation would use the
URI scheme as an identifier.
=item A property query string
See L<property(7)> for a more detailed description.
This is used to select more exactly which providers will get to offer
an implementation.
=back
The method object that is fetched can then be used with diverse other
functions that use them, for example L<EVP_DigestInit_ex(3)>.
=head3 Implicit fetch
I<NOTE: This section is mostly interesting to OpenSSL users.>
OpenSSL has a number of functions that return a method object with no
associated implementation, such as L<EVP_sha256(3)>,
L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for
compatibility with OpenSSL before version 3.0.
When they are used with functions like L<EVP_DigestInit_ex(3)> or
L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
fetched implicitly using default search criteria.
Implicit fetching can also occur with functions such as
L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is
supplied.
In this case an algorithm implementation is implicitly fetched using
default search criteria and an algorithm name that is consistent with
the type of EVP_PKEY being used.
=head1 OPENSSL PROVIDERS
OpenSSL comes with a set of providers.
All the algorithm names mentioned can be used as an algorithm
identifier to the appropriate fetching function.
=head2 Default provider
The default provider is built in as part of the F<libcrypto> library.
Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property "default=yes"
can be used as a search criterion for these implementations.
It currently offers the following named algorithms:
=over 4
=item Digests
SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
=item Symmetric ciphers
AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB,
AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1,
AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR,
AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM
=item Key Exchange
dhKeyAgreement
=back
=head2 FIPS provider
The FIPS provider is a dynamically loadable module, and must therefore
be loaded explicitly, either in code or through OpenSSL configuration
(see L<config(5)>).
Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property "fips=yes" can
be used as a search criterion for these implementations.
It currently offers the following FIPS approved named algorithms:
=over 4
=item Digests
SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
=item Symmetric ciphers
AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
=back
=head2 Legacy provider
The legacy provider is a dynamically loadable module, and must therefore
be loaded explicitly, either in code or through OpenSSL configuration
(see L<config(5)>).
Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property "legacy=yes" can be
used as a search criterion for these implementations.
It currently offers the following named algorithms:
=over 4
=item Digest algorithms:
RIPEMD160, MD2, MD4, MDC2, whirlpool.
=back
=head1 EXAMPLES
=head2 Fetching
Fetch any available implementation of SHA256 in the default context:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
...
EVP_MD_meth_free(md);
Fetch any available implementation of AES-128-CBC in the default context:
EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
...
EVP_CIPHER_meth_free(cipher);
Fetch an implementation of SHA256 from the default provider in the default
context:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
...
EVP_MD_meth_free(md);
Fetch an implementation of SHA256 that is not from the default provider in the
default context:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
...
EVP_MD_meth_free(md);
Fetch an implementation of SHA256 from the default provider in the specified
context:
EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
...
EVP_MD_meth_free(md);
Load the legacy provider into the default context and then fetch an
implementation of whirlpool from it:
/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
...
EVP_MD_meth_free(md);
Note that in the above example the property string "legacy=yes" is optional
since, assuming no other providers have been loaded, the only implementation of
the "whirlpool" algorithm is in the "legacy" provider. Also note that the
default provider should be explicitly loaded if it is required in addition to
other providers:
/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
...
EVP_MD_meth_free(md_whirlpool);
EVP_MD_meth_free(md_sha256);
=head1 SEE ALSO
L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
L<EVP_PKEY_derive_init_ex(3)>,
L<OPENSSL_CTX(3)>,
L<EVP_set_default_properties(3)>,
L<EVP_MD_fetch(3)>,
L<EVP_CIPHER_fetch(3)>,
L<EVP_KEYMGMT_fetch(3)>,
L<openssl-core.h(7)>,
L<provider-base(7)>,
L<provider-digest(7)>,
L<provider-cipher(7)>,
L<provider-keyexch(7)>
=head1 HISTORY
The concept of providers and everything surrounding them was
introduced in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 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
doc/man7/x509.pod
-1
View File
@@ -58,7 +58,6 @@ L<d2i_X509_CRL(3)>,
L<d2i_X509_NAME(3)>,
L<d2i_X509_REQ(3)>,
L<d2i_X509_SIG(3)>,
L<X509v3(3)>,
L<crypto(7)>
=head1 COPYRIGHT