mirror of
https://github.com/openssl/openssl.git
synced 2025-01-12 13:36:28 +08:00
b808665265
Renamed some values in core_names i.e Some DH specific names were changed to use DH instead of FFC. Added some strings values related to RSA keys. Moved set_params related docs out of EVP_PKEY_CTX_ctrl.pod into its own file. Updated Keyexchange and signature code and docs. Moved some common DSA/DH docs into a shared EVP_PKEY-FFC.pod. Moved Ed25519.pod into EVP_SIGNATURE-ED25519.pod and reworked it. Added some usage examples. As a result of the usage examples the following change was also made: ec allows OSSL_PKEY_PARAM_USE_COFACTOR_ECDH as a settable gen parameter. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11610)
99 lines
2.7 KiB
Plaintext
99 lines
2.7 KiB
Plaintext
=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
|