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

Latest update (add quic)

Browse Source
This commit is contained in:
Hakase
2020-07-12 19:52:18 +09:00
parent 3a6d64bb68
commit e85ee33eee
501 changed files with 19166 additions and 10232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man7/EVP_KDF-HKDF.pod
+8 -8
View File
@@ -87,7 +87,7 @@ an error will occur.
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);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an HKDF expand operation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function. When using
@@ -107,7 +107,7 @@ salt value "salt" and info value "label":
OSSL_PARAM params[5], *p = params;
kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -119,14 +119,14 @@ salt value "salt" and info value "label":
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -135,10 +135,10 @@ RFC 5869
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-KB.pod
+10 -10
View File
@@ -57,7 +57,7 @@ Depending on whether mac is CMAC or HMAC, either digest or cipher is required
A context for KBKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an KBKDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -76,7 +76,7 @@ Label "label", and Context "context".
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -90,12 +90,12 @@ Label "label", and Context "context".
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"context", strlen("context"));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
else if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret",
Label "label", and IV "sixteen bytes iv".
@@ -107,7 +107,7 @@ Label "label", and IV "sixteen bytes iv".
unsigned char *iv = "sixteen bytes iv";
kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
@@ -122,12 +122,12 @@ Label "label", and IV "sixteen bytes iv".
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
iv, strlen(iv));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
else if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -136,7 +136,7 @@ NIST SP800-108, IETF RFC 6803, IETF RFC 8009.
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-KRB5KDF.pod
+4 -4
View File
@@ -44,7 +44,7 @@ If a value is already set, the contents are replaced.
A context for KRB5KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of the KRB5KDF derivation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function, and MUST match the key
@@ -70,7 +70,7 @@ This example derives a key using the AES-128-CBC cipher:
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER,
@@ -87,7 +87,7 @@ This example derives a key using the AES-128-CBC cipher:
if (EVP_KDF_derive(kctx, out, outlen) <= 0)
/* Error */
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -96,7 +96,7 @@ RFC 3961
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
doc/man7/EVP_KDF-PBKDF2.pod
+3 -3
View File
@@ -82,9 +82,9 @@ SP800-132
=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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SCRYPT.pod
+8 -8
View File
@@ -66,7 +66,7 @@ Both r and p are parameters of type B<uint32_t>.
A context for scrypt can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an scrypt key derivation is specified via the
"keylen" parameter to the L<EVP_KDF_derive(3)> function.
@@ -82,7 +82,7 @@ This example derives a 64-byte long test vector using scrypt with the password
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
@@ -93,8 +93,8 @@ This example derives a 64-byte long test vector using scrypt with the password
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
@@ -115,7 +115,7 @@ This example derives a 64-byte long test vector using scrypt with the password
assert(!memcmp(out, expected, sizeof(out)));
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -124,9 +124,9 @@ RFC 7914
=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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SS.pod
+16 -16
View File
@@ -66,7 +66,7 @@ This parameter sets an optional value for fixedinfo, also known as otherinfo.
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);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an SSKDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -82,7 +82,7 @@ and fixedinfo value "label":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -92,14 +92,14 @@ and fixedinfo value "label":
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
fixedinfo value "label" and salt "salt":
@@ -110,7 +110,7 @@ fixedinfo value "label" and salt "salt":
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
@@ -124,14 +124,14 @@ fixedinfo value "label" and salt "salt":
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(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:
@@ -142,7 +142,7 @@ fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
OSSL_PARAM params[7], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
@@ -157,14 +157,14 @@ fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
"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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -173,9 +173,9 @@ 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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SSHKDF.pod
+6 -6
View File
@@ -87,7 +87,7 @@ A single char of value 70 (ASCII char 'F').
A context for SSHKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of the SSHKDF derivation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -111,7 +111,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -125,7 +125,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
*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)
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
/* Error */
if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
@@ -139,9 +139,9 @@ RFC 4253
=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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-TLS1_PRF.pod
+8 -8
View File
@@ -51,7 +51,7 @@ this should be more than enough for any normal use of the TLS PRF.
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);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The digest, secret value and seed must be set before a key is derived otherwise
an error will occur.
@@ -70,7 +70,7 @@ and seed value "seed":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -80,13 +80,13 @@ and seed value "seed":
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -95,9 +95,9 @@ 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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-X942.pod
+9 -9
View File
@@ -49,7 +49,7 @@ This parameter sets the CEK wrapping algorithm name.
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);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an X942KDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -71,9 +71,9 @@ keying material:
kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
if (kctx == NULL)
error("EVP_KDF_fetch");
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
if (kctx == NULL)
error("EVP_KDF_CTX_new");
error("EVP_KDF_new_ctx");
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -85,12 +85,12 @@ keying material:
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_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -99,9 +99,9 @@ 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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-X963.pod
+8 -8
View File
@@ -46,7 +46,7 @@ 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);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an X963KDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -62,7 +62,7 @@ value "label":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -72,14 +72,14 @@ value "label":
*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_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -88,9 +88,9 @@ value "label":
=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_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KEYEXCH-DH.pod
+98
View File
@@ -0,0 +1,98 @@
=pod
=head1 NAME
EVP_KEYEXCH-DH
- DH Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<DH> key type.
=head2 DH key exchange parameters
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
See L<provider-keyexch(7)/Common Key Exchange parameters>.
=back
=head1 EXAMPLES
The examples assume a host and peer both generate keys using the same
named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>.
Both the host and peer transfer their public key to each other.
To convert the peer's generated key pair to a public key in DER format in order
to transfer to the host:
EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
unsigned char *peer_pub_der = NULL;
int peer_pub_der_len;
peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
...
OPENSSL_free(peer_pub_der);
To convert the received peer's public key from DER format on the host:
const unsigned char *pd = peer_pub_der;
EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
...
EVP_PKEY_free(peer_pub_key);
To derive a shared secret on the host using the host's key and the peer's public
key:
/* It is assumed that the host_key and peer_pub_key are set up */
void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
{
unsigned int pad = 1;
OSSL_PARAM params[2];
unsigned char *secret = NULL;
size_t secret_len = 0;
EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
EVP_PKEY_derive_init(dctx);
/* Optionally set the padding */
params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
params[1] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(dctx, params);
EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
/* Get the size by passing NULL as the buffer */
EVP_PKEY_derive(dctx, NULL, &secret_len);
secret = OPENSSL_zalloc(secret_len);
EVP_PKEY_derive(dctx, secret, &secret_len);
...
OPENSSL_clear_free(secret, secret_len);
EVP_PKEY_CTX_free(dctx);
}
Very similar code can be used by the peer to derive the same shared secret
using the host's public key and the peer's generated key pair.
=head1 SEE ALSO
L<EVP_PKEY-DH(7)>,
L<EVP_PKEY-FFC(7)>,
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_KEYEXCH-ECDH.pod
+133
View File
@@ -0,0 +1,133 @@
=pod
=head1 NAME
EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<ECDH> key type.
=head2 ECDH Key Exchange parameters
=over 4
=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
Sets or gets the ECDH mode of operation for the associated key exchange ctx.
In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
can be used to select between the plain Diffie-Hellman (DH) or Cofactor
Diffie-Hellman (CDH) variants of the key exchange algorithm.
When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
on, off, or resetting it to the default for the private key associated with the
given key exchange ctx.
When getting, the value should be either 1 or 0, respectively signaling if the
cofactor mode is on or off.
See also L<provider-keymgmt(7)> for the related
B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
per-key basis.
=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
Sets or gets the Key Derivation Function type to apply within the associated key
exchange ctx.
=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Derivation Function associated with the given key
exchange ctx.
=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
Sets or gets the desired size for the output of the chosen Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
Sets the User Key Material to be used as part of the selected Key Derivation
Function associated with the given key exchange ctx.
=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
Gets a pointer to the User Key Material to be used as part of the selected
Key Derivation Function associated with the given key exchange ctx.
=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
Gets the size of the User Key Material to be used as part of the selected
Key Derivation Function associated with the given key exchange ctx.
=back
=head1 EXAMPLES
Keys for the host and peer must be generated as shown in
L<EVP_PKEY-EC(7)/Examples> using the same curve name.
The code to generate a shared secret for the normal case is identical to
L<EVP_KEYEXCH-DH(7)/Examples>.
To derive a shared secret on the host using the host's key and the peer's public
key but also using X963KDF with a user key material:
/* It is assumed that the host_key, peer_pub_key and ukm are set up */
void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
unsigned char *ukm, size_t ukm_len)
{
unsigned char secret[64];
size_t out_len = sizeof(secret);
size_t secret_len = out_len;
unsigned int pad = 1;
OSSL_PARAM params[6];
EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
EVP_PKEY_derive_init(dctx);
params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
"X963KDF", 0);
params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
"SHA1", 0);
params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
&out_len);
params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
ukm, ukm_len);
params[5] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(dctx, params);
EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
EVP_PKEY_derive(dctx, secret, &secret_len);
...
OPENSSL_clear_free(secret, secret_len);
EVP_PKEY_CTX_free(dctx);
}
=head1 SEE ALSO
L<EVP_PKEY-EC(7)>
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_KEYEXCH-X25519.pod
+50
View File
@@ -0,0 +1,50 @@
=pod
=head1 NAME
EVP_KEYEXCH-X25519,
EVP_KEYEXCH-X448
- X25519 and X448 Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<X25519> and B<X448> key types.
=head2 Key exchange parameters
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
See L<provider-keyexch(7)/Common Key Exchange parameters>.
=back
=head1 EXAMPLES
Keys for the host and peer can be generated as shown in
L<EVP_PKEY-X25519(7)/Examples>.
The code to generate a shared secret is identical to
L<EVP_KEYEXCH-DH(7)/Examples>.
=head1 SEE ALSO
L<EVP_PKEY-FFC(7)>,
L<EVP_PKEY-DH(7)>
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_MAC-BLAKE2.pod
+3 -3
View File
@@ -27,9 +27,9 @@ properties, to be used with EVP_MAC_fetch():
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().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -61,7 +61,7 @@ It is 32 and 64 respectively by default.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 HISTORY
doc/man7/EVP_MAC-CMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
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():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -37,7 +37,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -50,7 +50,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-GMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
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():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -39,7 +39,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -52,7 +52,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-HMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
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():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -41,7 +41,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
The "flags" parameter is passed directly to HMAC_CTX_set_flags().
The following parameter can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -54,7 +54,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>, L<HMAC(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-KMAC.pod
+3 -3
View File
@@ -27,9 +27,9 @@ properties, to be used with EVP_MAC_fetch():
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().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -50,7 +50,7 @@ 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_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-Poly1305.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
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():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -33,7 +33,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -46,7 +46,7 @@ The length of the "size" parameter should not exceed that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-Siphash.pod
+3 -3
View File
@@ -25,9 +25,9 @@ used with EVP_MAC_fetch():
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().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -40,7 +40,7 @@ The length of the "size" parameter should not exceed that of a B<size_t>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MD-common.pod
+2 -7
View File
@@ -7,11 +7,8 @@ EVP_MD-common - The OpenSSL EVP_MD implementations, common things
=head1 DESCRIPTION
All the OpenSSL EVP_MD implementations understand the following
L<OSSL_PARAM(3)> entries:
=over 4
Gettable with L<EVP_MD_get_params(3)>:
L<OSSL_PARAM(3)> entries that are
gettable with L<EVP_MD_get_params(3)>, as well as these:
=over 4
@@ -49,8 +46,6 @@ This value can also be retrieved with L<EVP_MD_flags(3)>.
=back
=back
=head1 SEE ALSO
L<EVP_MD_get_params(3)>, L<provider-digest(7)>
doc/man7/EVP_PKEY-DH.pod
+234
View File
@@ -0,0 +1,234 @@
=pod
=head1 NAME
EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support
=head1 DESCRIPTION
For B<DH> FFC key agreement, two classes of domain parameters can be used:
"safe" domain parameters that are associated with approved named safe-prime
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
parameters should only be used for backward compatibility with existing
applications that cannot be upgraded to use the approved safe-prime groups.
See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
For B<DH> that is not a named group) the FIPS186-4 standard specifies that the
values used for FFC parameter generation are also required for parameter
validation. This means that optional FFC domain parameter values for
I<seed>, I<pcounter> and I<gindex> may need to be stored for validation purposes.
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
(but the I<gindex> is not).
=head2 DH parameters
In addition to the common FCC parameters that all FFC keytypes should support
(see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype
implementation supports the following:
=over 4
=item "group" (B<OSSL_PKEY_PARAM_DH_GROUP>) <UTF8 string>
Set or gets a string that associates a B<DH> named safe prime group with known
values for I<p>, I<q> and I<g>.
The following values can be used by the OpenSSL's default and FIPS providers:
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
The following additional values can also be used by OpenSSL's default provider:
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
DH named groups can be easily validated since the parameters are well known.
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
retrieved.
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer>
Used for DH generation of safe primes using the old generator code.
It is recommended to use a named safe prime group instead, if domain parameter
validation is required. The default value is 2.
These are not named safe prime groups so setting this value for the OpenSSL FIPS
provider will instead choose a named safe prime group based on the size of I<p>.
=item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
Used for getting and setting the encoding of the DH public key used in a key
exchange message for the TLS protocol.
=back
=head2 DH domain parameter / key generation parameters
In addition to the common FCC key generation parameters that all FFC key types
should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the
B<DH> keytype implementation supports the following:
=over 4
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
Sets the type of parameter generation. For B<DH> valid values are:
=over 4
=item "fips186_4"
=item "default"
=item "fips186_2"
These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
=item "group"
This specifies that a named safe prime name will be chosen using the "pbits"
type.
=item "generator"
A safe prime generator. See the "safeprime-generator" type above.
=back
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'p'.
For "fips186_4" this must be 2048.
For "fips186_2" this must be 1024.
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer>
An optional value to set the maximum length of the generated private key.
The default valure used if this is not set is the maximum value of
BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
Where s is the security strength of the key which has values of
112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
=back
=head1 EXAMPLES
An B<EVP_PKEY> context can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
An B<DH> key can be generated with a named safe prime group by calling:
int priv_len = 2 * 112;
OSSL_PARAM params[3];
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
/* "priv_len" is optional */
params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_keygen_init(pctx);
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_gen(pctx, &pkey);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(pctx);
Legacy B<DH> domain parameters can be generated by calling:
unsigned int pbits = 2048;
unsigned int qbits = 256;
int gindex = 1;
OSSL_PARAM params[5];
EVP_PKEY *param_key = NULL;
EVP_PKEY_CTX *pctx = NULL;
pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
EVP_PKEY_paramgen_init(pctx);
params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
params[4] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_gen(pctx, &param_key);
EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
...
EVP_PKEY_free(param_key);
EVP_PKEY_CTX_free(pctx);
An B<DH> key can be generated using domain parameters by calling:
EVP_PKEY *key = NULL;
EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
EVP_PKEY_keygen_init(gctx);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);
=for comment TODO(3.0): To validate domain parameters, additional values used
during generation may be required to be set into the key.
=head1 CONFORMING TO
=over 4
=item RFC 7919 (TLS ffdhe named safe prime groups)
=item RFC 3526 (IKE modp named safe prime groups)
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
and "dh_2048_256").
=back
The following sections of SP800-56Ar3:
=over 4
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
=item Appendix D: FFC Safe-prime Groups
=back
The following sections of FIPS 186-4:
=over 4
=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
=item A.2.3 Generation of canonical generator g.
=item A.2.1 Unverifiable Generation of the Generator g.
=back
=head1 SEE ALSO
L<EVP_PKEY-FFC(7)>,
L<EVP_KEYEXCH-DH(7)>
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEYMGMT(3)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_PKEY-DSA.pod
+50 -209
View File
@@ -2,240 +2,77 @@
=head1 NAME
EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
- EVP_PKEY DSA and DH keytype and algorithm support
EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
=head1 DESCRIPTION
The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
providers.
The implementations support the basic DSA and DH keys, containing the public
and private keys I<pub> and I<priv> as well as the three main domain parameters
I<p>, I<q> and I<g>.
Finite field cryptography (FFC) is a method of implementing discrete logarithm
cryptography using finite field mathematics. DSA is an example of FFC and
Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
implemented as FFC.
For B<DH> FFC key agreement, two classes of domain parameters can be used:
"safe" domain parameters that are associated with approved named safe-prime
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
parameters should only be used for backward compatibility with existing
applications that cannot be upgraded to use the approved safe-prime groups.
For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard
specifies that the values used for FFC parameter generation are also required
for parameter validation.
For B<DSA> the FIPS186-4 standard specifies that the values used for FFC
parameter generation are also required for parameter validation.
This means that optional FFC domain parameter values for I<seed>, I<pcounter>
and I<gindex> may need to be stored for validation purposes.
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
(but the I<gindex> is not). For B<DSA> however, these fields are not stored in
the ASN1 data so they need to be stored externally if validation is required.
and I<gindex> may need to be stored for validation purposes. For B<DSA> these
fields are not stored in the ASN1 data so they need to be stored externally if
validation is required.
=head2 Common DH parameters
=head2 DSA parameters
=over 4
The B<DSA> key type supports the FFC parameters (see
L<EVP_PKEY-FFC(7)/FFC parameters>).
=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
=head2 DSA key generation parameters
A string that associates a B<DH> named safe prime group with known values for
I<p>, I<q> and I<g>.
The B<DSA> key type supports the FFC key generation parameters (see
L<EVP_PKEY-FFC(7)/FFC key generation parameters>
The following values can be used by the default and OpenSSL's FIPS providers:
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
The following restrictions apply to the "pbits" field:
The following additional values can also be used by the default provider:
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
DH named groups can be easily validated since the parameters are well known.
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
retrieved.
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
Used for DH generation of safe primes using the old generator code.
It is recommended to use a named safe prime group instead, if domain parameter
validation is required. The default value is 2.
These are not named safe prime groups so setting this value for the OpenSSL FIPS
provider will instead choose a named safe prime group based on the size of I<p>.
=back
=head2 Common DSA & DH parameters
In addition to the common parameters that all keytypes should support (see
L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
implementations support the following.
=over 4
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
The public key value.
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
The private key value.
=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
A DSA or Diffie-Hellman prime "p" value.
=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
A DSA or Diffie-Hellman prime "q" value.
=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
A DSA or Diffie-Hellman generator "g" value.
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
An optional domain parameter I<seed> value used during generation and validation
of I<p>, I<q> and canonical I<g>.
For validation this needs to set the I<seed> that was produced during generation.
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
Sets the index to use for canonical generation and verification of the generator
I<g>.
Set this to a positive value from 0..FF to use this mode. This I<gindex> can
then be reused during key validation to verify the value of I<g>. If this value
is not set or is -1 then unverifiable generation of the generator I<g> will be
used.
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
An optional domain parameter I<counter> value that is output during generation
of I<p>. This value must be saved if domain parameter validation is required.
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
For unverifiable generation of the generator I<g> this value is output during
generation of I<g>. Its value is the first integer larger than one that
satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
An optional informational cofactor parameter that should equal (p - 1) / q.
=back
=head2 DSA / DH key generation (FFC) parameters
The following Key Generation types are available for the built-in FFC algorithms:
=over 4
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
Sets the type of parameter generation. For DH Valid values are:
=over 4
=item "fips186_4"
The current standard. This is the default value.
=item "default"
This is an alias to use the latest implemented standard.
It is currently set to "fips186_4".
=item "group"
This specifies that a named safe prime name will be chosen using the "pbits"
type.
=item "fips186_2"
The old standard that should only be used for legacy purposes.
=item "generator"
A safe prime generator. See the "safeprime-generator" type.
=back
For DSA valid values are one of "default", "fips186_4" or "fips186_2" as
described above.
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'p'.
For "fips186_4" this must be 2048 for DH, and either of 2048 or 3072 for DSA.
For "fips186_4" this must be either 2048 or 3072.
For "fips186_2" this must be 1024.
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
=head1 EXAMPLES
Sets the size (in bits) of the prime 'q'.
An B<EVP_PKEY> context can be obtained by calling:
For "fips186_4" this can be either 224 or 256.
For "fips186_2" this has a size of 160.
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string>
An B<DH> domain parameters key can be generated by calling:
Sets the Digest algorithm to be used as part of the Key Generation Function
associated with the given Key Generation I<ctx>.
This must also be set for key validation.
unsigned int pbits = 2048;
unsigned int qbits = 256;
int gindex = 1;
OSSL_PARAM params[5];
EVP_PKEY *param_key = NULL;
EVP_PKEY_CTX *pctx = NULL;
=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
EVP_PKEY_paramgen_init(pctx);
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Generation Function associated with the given key
generation I<ctx>. This may also be set for key validation.
params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
params[4] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
EVP_PKEY_gen(pctx, &param_key);
EVP_PKEY_CTX_free(pctx);
For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
instead of generating a random seed internally. This should be used for
testing purposes only. This will either produce fixed values for the generated
parameters OR it will fail if the seed did not generate valid primes.
EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
An B<DSA> key can be generated using domain parameters by calling:
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
EVP_PKEY *key = NULL;
EVP_PKEY_CTX *gctx = NULL;
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
These types are described above.
=back
gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
EVP_PKEY_keygen_init(gctx);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_CTX_free(gctx);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
=head1 CONFORMING TO
=over 4
=item RFC 7919 (TLS ffdhe named safe prime groups)
=item RFC 3526 (IKE modp named safe prime groups)
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
and "dh_2048_256").
=back
The following sections of SP800-56Ar3:
=over 4
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
=item Appendix D: FFC Safe-prime Groups
=back
The following sections of FIPS 186-4:
=over 4
@@ -250,9 +87,13 @@ The following sections of FIPS 186-4:
=head1 SEE ALSO
L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
L<EVP_SIGNATURE-DSA(7)>, L<EVP_KEYEXCH-DH(7)>
L<EVP_PKEY-FFC(7)>,
L<EVP_SIGNATURE-DSA(7)>
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEYMGMT(3)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>
=head1 COPYRIGHT
doc/man7/EVP_PKEY-EC.pod
+69 -5
View File
@@ -2,7 +2,9 @@
=head1 NAME
EVP_PKEY-EC - EVP_PKEY EC keytype and algorithm support
EVP_PKEY-EC,
EVP_KEYMGMT-EC
- EVP_PKEY EC keytype and algorithm support
=head1 DESCRIPTION
@@ -24,9 +26,8 @@ Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
if the value is zero. The cofactor variant multiplies the shared secret by the
EC curve's cofactor (note for some curves the cofactor is 1).
=for comment The following link should become L<EVP_KEYEXCH-ECDH(7)>
See also L<provider-keyexch(7)> for the related
See also L<EVP_KEYEXCH-ECDH(7)> for the related
B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
per-operation basis.
@@ -38,6 +39,11 @@ The public key value in EC point format.
The private key value.
=item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
Used for getting and setting the encoding of the EC public key used in key
exchange message for the TLS protocol.
=back
=head1 EXAMPLES
@@ -47,10 +53,68 @@ An B<EVP_PKEY> context can be obtained by calling:
EVP_PKEY_CTX *pctx =
EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
calling:
EVP_PKEY *key = NULL;
OSSL_PARAM params[2];
EVP_PKEY_CTX *gctx =
EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
EVP_PKEY_keygen_init(gctx);
params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_EC_NAME,
"P-256", 0);
params[1] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(gctx, params);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);
An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
"K-571" named group by calling:
int use_cdh = 1;
EVP_PKEY *key = NULL;
OSSL_PARAM params[3];
EVP_PKEY_CTX *gctx =
EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
EVP_PKEY *key = NULL;
OSSL_PARAM params[3];
EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
EVP_PKEY_keygen_init(gctx);
params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_EC_NAME,
"K-571", 0);
/*
* This curve has a cofactor that is not 1 - so setting CDH mode changes
* the behaviour. For many curves the cofactor is 1 - so setting this has
* no effect.
*/
params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
&use_cdh);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(gctx, params);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);
=head1 SEE ALSO
L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
L<EVP_SIGNATURE-ECDSA(7)>, L<EVP_KEYEXCH-ECDH(7)>
L<EVP_KEYMGMT(3)>,
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_SIGNATURE-ECDSA(7)>,
L<EVP_KEYEXCH-ECDH(7)>
=head1 COPYRIGHT
doc/man7/EVP_PKEY-FFC.pod
+199
View File
@@ -0,0 +1,199 @@
=pod
=head1 NAME
EVP_PKEY-FFC - EVP_PKEY DSA and DH shared FFC parameters.
=head1 DESCRIPTION
Finite field cryptography (FFC) is a method of implementing discrete logarithm
cryptography using finite field mathematics. DSA is an example of FFC and
Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
implemented as FFC.
The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
providers.
The implementations support the basic DSA and DH keys, containing the public
and private keys I<pub> and I<priv> as well as the three main domain parameters
I<p>, I<q> and I<g>.
For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard
specifies that the values used for FFC parameter generation are also required
for parameter validation.
This means that optional FFC domain parameter values for I<seed>, I<pcounter>
and I<gindex> may need to be stored for validation purposes.
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
(but the I<gindex> is not). For B<DSA> however, these fields are not stored in
the ASN1 data so they need to be stored externally if validation is required.
=head2 FFC parameters
In addition to the common parameters that all keytypes should support (see
L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
implementations support the following.
=over 4
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
The public key value.
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
The private key value.
=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
A DSA or Diffie-Hellman prime "p" value.
=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
A DSA or Diffie-Hellman prime "q" value.
=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
A DSA or Diffie-Hellman generator "g" value.
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
An optional domain parameter I<seed> value used during generation and validation
of I<p>, I<q> and canonical I<g>.
For validation this needs to set the I<seed> that was produced during generation.
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
Sets the index to use for canonical generation and verification of the generator
I<g>.
Set this to a positive value from 0..FF to use this mode. This I<gindex> can
then be reused during key validation to verify the value of I<g>. If this value
is not set or is -1 then unverifiable generation of the generator I<g> will be
used.
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
An optional domain parameter I<counter> value that is output during generation
of I<p>. This value must be saved if domain parameter validation is required.
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
For unverifiable generation of the generator I<g> this value is output during
generation of I<g>. Its value is the first integer larger than one that
satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
An optional informational cofactor parameter that should equal to (p - 1) / q.
=back
=head2 FFC key generation parameters
The following key generation types are available for DSA and DH algorithms:
=over 4
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
Sets the type of parameter generation. The shared valid values are:
=over 4
=item "fips186_4"
The current standard. This is the default value.
=item "fips186_2"
The old standard that should only be used for legacy purposes.
=item "default"
This is an alias to use the latest implemented standard.
It is currently set to "fips186_4".
=back
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'p'.
=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'q'.
For "fips186_4" this can be either 224 or 256.
For "fips186_2" this has a size of 160.
=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string>
Sets the Digest algorithm to be used as part of the Key Generation Function
associated with the given Key Generation I<ctx>.
This must also be set for key validation.
=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Generation Function associated with the given key
generation I<ctx>. This may also be set for key validation.
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
instead of generating a random seed internally. This should be used for
testing purposes only. This will either produce fixed values for the generated
parameters OR it will fail if the seed did not generate valid primes.
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
These types are described above.
=back
=head1 CONFORMING TO
The following sections of SP800-56Ar3:
=over 4
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
=back
The following sections of FIPS 186-4:
=over 4
=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
=item A.2.3 Generation of canonical generator g.
=item A.2.1 Unverifiable Generation of the Generator g.
=back
=head1 SEE ALSO
L<EVP_PKEY-DSA(7)>,
L<EVP_PKEY-DH(7)>,
L<EVP_SIGNATURE-DSA(7)>,
L<EVP_KEYEXCH-DH(7)>
L<EVP_KEYMGMT(3)>,
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_PKEY-RSA.pod
+14 -5
View File
@@ -121,6 +121,13 @@ The value should be the number of primes for the generated B<RSA> key. The
default is 2. It isn't permitted to specify a larger number of primes than
10. Additionally, the number of primes is limited by the length of the key
being generated so the maximum number could be less.
Some providers may only support a value of 2.
=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
The RSA "e" value. The value may be any odd number greater than or equal to
65537. The default value is 65537.
For legacy reasons a value of 3 is currently accepted but is deprecated.
=back
@@ -158,15 +165,17 @@ An B<RSA> key can be generated with key generation parameters:
unsigned int bits = 4096;
OSSL_PARAM params[3];
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx =
EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
params[0] = OSSL_PARAM_construct_uint("bits", bits);
params[1] = OSSL_PARAM_construct_uint("primes", primes);
params[2] = OSSL_PARAM_END;
EVP_PKEY_keygen_init(pctx);
params[0] = OSSL_PARAM_construct_uint("bits", &bits);
params[1] = OSSL_PARAM_construct_uint("primes", &primes);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_gen(pctx, &pkey);
EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
EVP_PKEY_CTX_free(pctx);
=head1 SEE ALSO
doc/man7/EVP_PKEY-X25519.pod
+9
View File
@@ -15,6 +15,8 @@ private key I<priv>.
In the FIPS provider they are non-approved algorithms and do not have the
"fips=yes" property set.
No additional parameters can be set during key generation.
=head2 Common X25519, X448, ED25519 and ED448 parameters
@@ -32,6 +34,11 @@ The public key value.
The private key value.
=item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
Used for getting and setting the encoding of the public key used in a key exchange
message for the TLS protocol.
=back
=head2 ED25519 and ED448 parameters
@@ -50,6 +57,8 @@ The empty string, signifying that no digest may be specified.
=item RFC 8032
=item RFC 8410
=back
=head1 EXAMPLES
doc/man7/EVP_SIGNATURE-DSA.pod
+58
View File
@@ -0,0 +1,58 @@
=pod
=head1 NAME
EVP_SIGNATURE-DSA
- The B<EVP_PKEY> DSA signature implementation
=head1 DESCRIPTION
Support for computing DSA signatures.
See L<EVP_PKEY-DSA(7)> for information related to DSA keys.
=head2 Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params().
This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
and before calling EVP_PKEY_sign() or EVP_PKEY_verify().
=over 4
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
The settable parameters are described in L<provider-signature(7)>.
=back
The following signature parameters can be retrieved using
EVP_PKEY_CTX_get_params().
=over 4
=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
The gettable parameters are described in L<provider-signature(7)>.
=back
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_params(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<provider-signature(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_SIGNATURE-ECDSA.pod
+57
View File
@@ -0,0 +1,57 @@
=pod
=head1 NAME
EVP_SIGNATURE-ECDSA - The EVP_PKEY ECDSA signature implementation.
=head1 DESCRIPTION
Support for computing ECDSA signatures.
See L<EVP_PKEY-EC(7)> for information related to EC keys.
=head2 ECDSA Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params().
This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
and before calling EVP_PKEY_sign() or EVP_PKEY_verify().
=over 4
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
These parameters are described in L<provider-signature(7)>.
=back
The following signature parameters can be retrieved using
EVP_PKEY_CTX_get_params().
=over 4
=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
The parameters are described in L<provider-signature(7)>.
=back
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_params(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<provider-signature(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/Ed25519.pod → doc/man7/EVP_SIGNATURE-ED25519.pod
+25 -24
View File
@@ -2,6 +2,8 @@
=head1 NAME
EVP_SIGNATURE-ED25519,
EVP_SIGNATURE-ED448,
Ed25519,
Ed448
- EVP_PKEY Ed25519 and Ed448 support
@@ -13,9 +15,10 @@ one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448
(see RFC8032). It has associated private and public key formats compatible with
RFC 8410.
No additional parameters can be set during key generation, one-shot signing or
verification. In particular, because PureEdDSA is used, a digest must B<NOT> be
specified when signing or verifying.
No additional parameters can be set during one-shot signing or verification.
In particular, because PureEdDSA is used, a digest must B<NOT> be specified when
signing or verifying.
See L<EVP_PKEY-X25519(7)> for information related to B<X25519> and B<X448> keys.
=head1 NOTES
@@ -31,14 +34,6 @@ Applications wishing to sign certificates (or other structures such as
CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign()
or X509_sign_ctx() in the usual way.
A context for the B<Ed25519> algorithm can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
For the B<Ed448> algorithm a context can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL);
Ed25519 or Ed448 private keys can be set directly using
L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
@@ -56,23 +51,29 @@ specified, then both Ed25519 and Ed448 are benchmarked.
=head1 EXAMPLES
This example generates an B<ED25519> private key and writes it to standard
output in PEM format:
To sign a message using a ED25519 or ED448 key:
#include <openssl/evp.h>
#include <openssl/pem.h>
...
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
EVP_PKEY_keygen_init(pctx);
EVP_PKEY_keygen(pctx, &pkey);
EVP_PKEY_CTX_free(pctx);
PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
{
size_t sig_len;
unsigned char *sig = NULL;
EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key);
/* Calculate the requires size for the signature by passing a NULL buffer */
EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
sig = OPENSSL_zalloc(sig_len);
EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len);
...
OPENSSL_free(sig);
EVP_MD_CTX_free(md_ctx);
}
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_keygen(3)>,
L<EVP_PKEY-X25519(7)>
L<provider-signature(7)>,
L<EVP_DigestSignInit(3)>,
L<EVP_DigestVerifyInit(3)>,
doc/man7/EVP_SIGNATURE-RSA.pod
+112
View File
@@ -0,0 +1,112 @@
=pod
=head1 NAME
EVP_SIGNATURE-RSA
- The EVP_PKEY RSA signature implementation
=head1 DESCRIPTION
Support for computing RSA signatures.
See L<EVP_PKEY-RSA(7)> for information related to RSA keys.
=head2 Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params().
This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
and before calling EVP_PKEY_sign() or EVP_PKEY_verify().
=over 4
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
These common parameters are described in L<provider-signature(7)>.
=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
The type of padding to be used. Its value can be one of the following:
=over 4
=item "none" (B<OSSL_PKEY_RSA_PAD_MODE_NONE>)
=item "pkcs1" (B<OSSL_PKEY_RSA_PAD_MODE_PKCSV15>)
=item "sslv23" (B<OSSL_PKEY_RSA_PAD_MODE_SSLV23>)
=item "x931" (B<OSSL_PKEY_RSA_PAD_MODE_X931>)
=item "pss" (B<OSSL_PKEY_RSA_PAD_MODE_PSS>)
=back
=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode.
=item "mgf1-properties" (B<OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES>) <UTF8 string>
Sets the name of the property query associated with the "mgf1-digest" algorithm.
NULL is used if this optional value is not set.
=item "pss-saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <UTF8 string>
Set or get the "pss" mode minimum salt length. The value can either be a string
value representing a number or one of the following:
=over 4
=item "digest" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST>)
Use the same length as the digest size.
=item "max" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_MAX>)
Use the maximum salt length.
=item "auto" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO>)
Auto detect the salt length.
=back
=back
The following signature parameters can be retrieved using
EVP_PKEY_CTX_get_params().
=over 4
=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
This common parameter is described in L<provider-signature(7)>.
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
These parameters are as described above.
=back
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_params(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<provider-signature(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/OSSL_PROVIDER-FIPS.pod
+12 -2
View File
@@ -18,9 +18,9 @@ defined:
=over 4
"provider=default"
=item "provider=default"
"fips=yes"
=item "fips=yes"
=back
@@ -102,6 +102,16 @@ The OpenSSL FIPS provider supports these operations and algorithms:
=item DH, see L<EVP_KEYEXCH-DH(7)>
=item ECDH, see L<EVP_KEYEXCH-ECDH(7)>
=item X25519, see L<EVP_KEYEXCH-X25519(7)>
This has the property "provider=fips,fips=no"
=item X448, see L<EVP_KEYEXCH-X448(7)>
This has the property "provider=fips,fips=no"
=back
=head2 Asymmetric Signature
doc/man7/OSSL_PROVIDER-default.pod
+3 -1
View File
@@ -17,7 +17,7 @@ defined:
=over 4
"provider=default"
=item "provider=default"
=back
@@ -136,6 +136,8 @@ The OpenSSL default provider supports these operations and algorithms:
=item KRB5KDF, see L<EVP_KDF-KRB5KDF(7)>
=item X963KDF, see L<EVP_KDF-X963(7)>
=back
=head2 Key Exchange
doc/man7/OSSL_PROVIDER-legacy.pod
+2 -2
View File
@@ -15,12 +15,12 @@ We can consider this the retirement home of cryptographic algorithms.
=head2 Properties
The implementations in this provider specifically have these property
The implementations in this provider specifically has this property
defined:
=over 4
"provider=legacy"
=item "provider=legacy"
=back
doc/man7/openssl-core_names.h.pod
+49
View File
@@ -0,0 +1,49 @@
=pod
=head1 NAME
openssl/core_names.h - OpenSSL provider parameter names
=head1 SYNOPSIS
#include <openssl/core_names.h>
=head1 DESCRIPTION
The F<< <openssl/core_names.h> >> header defines a multitude of macros
for L<OSSL_PARAM(3)> names, algorithm names and other known names used
with OpenSSL's providers, made available for practical purposes only.
Existing names are further described in the manuals for OpenSSL's
providers (see L</SEE ALSO>) and the manuals for each algorithm they
provide (listed in those provider manuals).
=head1 SEE ALSO
L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
L<OSSL_PROVIDER-legacy(7)>
=head1 HISTORY
The macros described here were added in OpenSSL 3.0.
=head1 CAVEATS
I<This header file does not constitute a general registry of names>.
Providers that implement new algorithms are to be responsible for
their own parameter names.
However, authors of provider that implement their own variants of
algorithms that OpenSSL providers support will want to pay attention
to the names provided in this header to work in a compatible manner.
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/openssl-core_numbers.h.pod
+56
View File
@@ -0,0 +1,56 @@
=pod
=head1 NAME
openssl/core_numbers.h
- OpenSSL provider dispatch numbers and function types
=head1 SYNOPSIS
#include <openssl/core_numbers.h>
=head1 DESCRIPTION
The F<< <openssl/core_numbers.h> >> header defines all the operation
numbers, dispatch numbers and provider interface function types
currently available.
The operation and dispatch numbers are represented with macros, which
are named as follows:
=over 4
=item operation numbers
These macros have the form C<OSSL_OP_I<opname>>.
=item dipatch numbers
These macros have the form C<OSSL_FUNC_I<opname>_I<funcname>>, where
C<I<opname>> is the same as in the macro for the operation this
function belongs to.
=back
With every dispatch number, there is an associated function type.
For further information, please see the L<provider(7)>
=head1 SEE ALSO
L<provider(7)>
=head1 HISTORY
The types and macros described here were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/provider-base.pod
+39 -9
View File
@@ -234,22 +234,52 @@ useless without at least provider_query_operation(), and
provider_gettable_params() is fairly useless if not accompanied by
provider_get_params().
=head2 Core parameters
=head2 Provider parameters
core_get_params() understands the following known parameters:
provider_get_params() can return the following provider parameters to the core:
=over 4
=item "openssl-version"
=item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8_ptr>
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>.
This points to a string that should give a unique name for the provider.
=item "provider-name"
=item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8_ptr>
This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
OpenSSL libraries' idea of what the calling provider is called.
This points to a string that is a version number associated with this provider.
OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
for any third party provider. This string is for informational purposes only.
=item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8_ptr>
This points to a string that is a build information associated with this provider.
OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
different for any third party provider.
=back
provider_gettable_params() should return the above parameters.
=head2 Core parameters
core_get_params() can retrieve the following core parameters for each provider:
=over 4
=item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8_ptr>
This points to the OpenSSL libraries' full version string, i.e. the string
expanded from the macro B<OPENSSL_VERSION_STR>.
=item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8_ptr>
This points to the OpenSSL libraries' idea of what the calling provider is named.
=item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8_ptr>
This points to a string containing the full filename of the providers
module file.
=back
doc/man7/provider-keyexch.pod
+6 -58
View File
@@ -131,12 +131,12 @@ written to I<*secretlen>.
OP_keyexch_set_ctx_params() sets key exchange parameters associated with the
given provider side key exchange context I<ctx> to I<params>,
see L</Key Exchange Parameters>.
see L</Common Key Exchange parameters>.
Any parameter settings are additional to any that were previously set.
OP_keyexch_get_ctx_params() gets key exchange parameters associated with the
given provider side key exchange context I<ctx> into I<params>,
see L</Key Exchange Parameters>.
see L</Common Key Exchange parameters>.
OP_keyexch_settable_ctx_params() yields a constant B<OSSL_PARAM> array that
describes the settable parameters, i.e. parameters that can be used with
@@ -152,15 +152,13 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
Notice that not all settable parameters are also gettable, and vice versa.
=head2 Key Exchange Parameters
=head2 Common Key Exchange parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
the OP_keyexch_set_ctx_params() and OP_keyexch_get_ctx_params() functions.
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:
Common parameters currently recognised by built-in key exchange algorithms are
as follows.
=over 4
@@ -168,63 +166,13 @@ algorithms:
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.
Setting a value 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.
=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
Sets/gets the ECDH mode of operation for the associated key exchange ctx.
In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
can be used to select between the plain Diffie-Hellman (DH) or Cofactor
Diffie-Hellman (CDH) variants of the key exchange algorithm.
When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
on, off, or resetting it to the default for the private key associated with the
given key exchange ctx.
When getting, the value should be either 1 or 0, respectively signaling if the
cofactor mode is on or off.
See also L<provider-keymgmt(7)> for the related
B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
per-key basis.
=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
Sets/gets the Key Derivation Function type to apply within the associated key
exchange ctx.
=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
Sets/gets the Digest algorithm to be used as part of the Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Derivation Function associated with the given key
exchange ctx.
=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
Sets/gets the desired size for the output of the chosen Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
Sets/gets User Key Material to be used as part of the selected Key Derivation
Function associated with the given key exchange ctx.
=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
Sets/gets the size of the User Key Material to be used as part of the selected
Key Derivation Function associated with the given key exchange ctx.
=back
=head1 RETURN VALUES
doc/man7/provider-signature.pod
+9 -6
View File
@@ -303,7 +303,7 @@ initialised verification context is passed in the I<ctx> parameter. The data to
verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be
verified is in I<sig> which is I<siglen> bytes long.
=head2 Signature Parameters
=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.
@@ -314,17 +314,20 @@ OP_signature_set_ctx_params() sets the signature parameters associated with the
given provider side signature context I<ctx> to I<params>.
Any parameter settings are additional to any that were previously set.
Parameters currently recognised by built-in signature algorithms are as
Common 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.
functions. It is required in order to calculate the "algorithm-id".
= item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
Sets the name of the property query associated with the "digest" algorithm.
NULL is used if this optional value is not set.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
@@ -358,7 +361,7 @@ 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.
=head2 MD Parameters
=head2 MD parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
the OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
doc/man7/proxy-certificates.pod
+18 -20
View File
@@ -57,24 +57,22 @@ See L</NOTES> for a discussion on this requirement.
Creating proxy certificates can be done using the L<openssl-x509(1)>
command, with some extra extensions:
[ v3_proxy ]
[ proxy ]
# A proxy certificate MUST NEVER be a CA certificate.
basicConstraints=CA:FALSE
basicConstraints = CA:FALSE
# Usual authority key ID
authorityKeyIdentifier=keyid,issuer:always
authorityKeyIdentifier = keyid,issuer:always
# The extension which marks this certificate as a proxy
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
proxyCertInfo = critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
It's also possible to specify the proxy extension in a separate section:
proxyCertInfo=critical,@proxy_ext
proxyCertInfo = critical,@proxy_ext
[ proxy_ext ]
language=id-ppl-anyLanguage
pathlen=0
policy=text:BC
language = id-ppl-anyLanguage
pathlen = 0
policy = text:BC
The policy value has a specific syntax, I<syntag>:I<string>, where the
I<syntag> determines what will be done with the string. The following
@@ -99,12 +97,12 @@ colons between each byte (every second hex digit):
indicates that the text of the policy should be taken from a file.
The string is then a filename. This is useful for policies that are
large (more than a few lines, e.g. XML documents).
more than a few lines, such as XML or other markup.
=back
I<NOTE: The proxy policy value is what determines the rights granted
to the process during the proxy certificate. It's up to the
Note that the proxy policy value is what determines the rights granted
to the process during the proxy certificate, and it is up to the
application to interpret and combine these policies.>
With a proxy extension, creating a proxy certificate is a matter of
@@ -112,23 +110,23 @@ two commands:
openssl req -new -config proxy.cnf \
-out proxy.req -keyout proxy.key \
-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1"
-subj "/DC=org/DC=openssl/DC=users/CN=proxy"
openssl x509 -req -CAcreateserial -in proxy.req -out proxy.crt \
-CA user.crt -CAkey user.key -days 7 \
-extfile proxy.cnf -extensions v3_proxy1
-extfile proxy.cnf -extensions proxy
You can also create a proxy certificate using another proxy
certificate as issuer (note: using a different configuration
section for the proxy extensions):
certificate as issuer. Note that this example uses a different
configuration section for the proxy extensions:
openssl req -new -config proxy.cnf \
-out proxy2.req -keyout proxy2.key \
-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1/CN=proxy 2"
-subj "/DC=org/DC=openssl/DC=users/CN=proxy/CN=proxy 2"
openssl x509 -req -CAcreateserial -in proxy2.req -out proxy2.crt \
-CA proxy.crt -CAkey proxy.key -days 7 \
-extfile proxy.cnf -extensions v3_proxy2
-extfile proxy.cnf -extensions proxy_2
=head2 Using proxy certs in applications
@@ -353,7 +351,7 @@ L<RFC 3820|https://tools.ietf.org/html/rfc3820>
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy