root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man3/DH_generate_key.pod

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

83 lines
2.7 KiB
Plaintext
Raw Normal View History

Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
=pod
=head1 NAME
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
DH_generate_key, DH_compute_key, DH_compute_key_padded - perform
Diffie-Hellman key exchange
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
=head1 SYNOPSIS
#include <openssl/dh.h>
Clarify the deprecation warnings in the docs There was recently an instance where a user was confused by the deprecation warnings in the docs. They believed the warning applied to the immediately preceding function declarations, when it fact it applied to the following function declarations. https://mta.openssl.org/pipermail/openssl-users/2021-December/014665.html We clarify the wording to make it clear that the warning applies to the following functions. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/17180)
2021-12-02 19:33:49 +08:00
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
see L<openssl_user_macros(7)>:
Deprecate the low level Diffie-Hellman functions. Use of the low level DH functions has been informally discouraged for a long time. We now formally deprecate them. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11024)
2020-02-03 17:05:31 +08:00
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
int DH_generate_key(DH *dh);
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
int DH_compute_key(unsigned char *key, const BIGNUM *pub_key, DH *dh);
int DH_compute_key_padded(unsigned char *key, const BIGNUM *pub_key, DH *dh);
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
=head1 DESCRIPTION
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
All of the functions described on this page are deprecated.
Deprecate the low level Diffie-Hellman functions. Use of the low level DH functions has been informally discouraged for a long time. We now formally deprecate them. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11024)
2020-02-03 17:05:31 +08:00
Applications should instead use L<EVP_PKEY_derive_init(3)>
and L<EVP_PKEY_derive(3)>.
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
DH_generate_key() performs the first step of a Diffie-Hellman key
exchange by generating private and public DH values. By calling
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
DH_compute_key() or DH_compute_key_padded(), these are combined with
the other party's public value to compute the shared key.
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
DH_generate_key() expects B<dh> to contain the shared parameters
B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
Undo DH_generate_key() change: s3_srvr.c was using it correctly
2001-07-28 06:34:25 +08:00
unless B<dh-E<gt>priv_key> is already set, and computes the
corresponding public value B<dh-E<gt>pub_key>, which can then be
published.
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
DH_compute_key() computes the shared secret from the private DH value
in B<dh> and the other party's public value in B<pub_key> and stores
it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
The padding style is RFC 5246 (8.1.2) that strips leading zero bytes.
It is not constant time due to the leading zero bytes being stripped.
The return value should be considered public.
DH_compute_key_padded() is similar but stores a fixed number of bytes.
The padding style is NIST SP 800-56A (C.1) that retains leading zero bytes.
It is constant time due to the leading zero bytes being retained.
The return value should be considered public.
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
=head1 RETURN VALUES
DH_generate_key() returns 1 on success, 0 otherwise.
DH_compute_key() returns the size of the shared secret on success, -1
on error.
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
DH_compute_key_padded() returns B<DH_size(dh)> on success, -1 on error.
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
The error codes can be obtained by L<ERR_get_error(3)>.
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
=head1 SEE ALSO
Deprecate the low level Diffie-Hellman functions. Use of the low level DH functions has been informally discouraged for a long time. We now formally deprecate them. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11024)
2020-02-03 17:05:31 +08:00
L<EVP_PKEY_derive(3)>,
Fix referenses in section 3 manuals Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1900)
2016-11-11 16:33:09 +08:00
L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<DH_size(3)>
Document the DH library, and make some minor changes along the way.
2000-01-23 04:05:23 +08:00
Deprecate the low level Diffie-Hellman functions. Use of the low level DH functions has been informally discouraged for a long time. We now formally deprecate them. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11024)
2020-02-03 17:05:31 +08:00
=head1 HISTORY
[crypto/dh] side channel hardening for computing DH shared keys Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13783)
2021-01-05 19:08:09 +08:00
DH_compute_key_padded() was added in OpenSSL 1.0.2.
All of these functions were deprecated in OpenSSL 3.0.
Deprecate the low level Diffie-Hellman functions. Use of the low level DH functions has been informally discouraged for a long time. We now formally deprecate them. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11024)
2020-02-03 17:05:31 +08:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update copyright year Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/13999)
2021-01-28 20:54:57 +08:00
Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
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