Commit 6a2da303 authored Aug 09, 2017 by Paul Yang Committed by Rich Salz Aug 09, 2017

Add XXX_security_bits documentation



This is a 'code health' commit to respond to this round of code health
Tuesday...

Reviewed-by: Andy Polyakov <appro@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4099)

parent 7a301f08

doc/man3/BN_security_bits.pod

0 → 100644

+51 −0

Original line number	Diff line number	Diff line
		=pod

		=head1 NAME

		BN_security_bits - returns bits of security based on given numbers

		=head1 SYNOPSIS

		#include <openssl/bn.h>

		int BN_security_bits(int L, int N);

		=head1 DESCRIPTION

		BN_security_bits() returns the number of bits of security provided by a
		specific algorithm and a particular key size. The bits of security is
		defined in NIST SP800-57. Currently, BN_security_bits() support two types
		of asymmetric algorithms: the FFC (Finite Field Cryptography) and IFC
		(Integer Factorization Cryptography). For FFC, e.g., DSA and DH, both
		parameters B<L> and B<N> are used to decide the bits of security, where
		B<L> is the size of the public key and B<N> is the size of the private
		key. For IFC, e.g., RSA, only B<L> is used and it's commonly considered
		to be the key size (modulus).

		=head1 RETURN VALUES

		Number of security bits.

		=head1 NOTES

		ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits()
		function. The symmetric algorithms are not covered neither.

		=head1 HISTORY

		BN_security_bits() was added in OpenSSL 1.1.0.

		=head1 SEE ALSO

		L<DH_security_bits(3)>, L<DSA_security_bits(3)>, L<RSA_security_bits(3)>

		=head1 COPYRIGHT

		Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.

		Licensed under the OpenSSL license (the "License"). You may not use
		this file except in compliance with the License. You can obtain a copy
		in the file LICENSE in the source distribution or at
		L<https://www.openssl.org/source/license.html>.

		=cut

doc/man3/DH_size.pod

+17 −7

Original line number	Diff line number	Diff line
		@@ -2,7 +2,8 @@

		=head1 NAME

		DH_size, DH_bits - get Diffie-Hellman prime size
		DH_size, DH_bits, DH_security_bits - get Diffie-Hellman prime size and
		security bits

		=head1 SYNOPSIS

		@@ -12,19 +13,28 @@ int DH_size(const DH *dh);

		int DH_bits(const DH *dh);

		int DH_security_bits(const DH *dh);

		=head1 DESCRIPTION

		DH_size() returns the Diffie-Hellman prime size in bytes. It can be used
		to determine how much memory must be allocated for the shared secret
		computed by DH_compute_key().
		computed by L<DH_compute_key(3)>.

		DH_bits() returns the number of significant bits.

		B<dh> and B<dh-E<gt>p> must not be B<NULL>.

		DH_security_bits() returns the number of security bits of the given B<dh>
		key. See L<BN_security_bits(3)>.

		=head1 RETURN VALUE

		The size.
		DH_size() returns the prime size of Diffie-Hellman in bytes.

		DH_bits() returns the number of bits in the key.

		DH_security_bits() returns the number of security bits.

		=head1 SEE ALSO

		@@ -37,7 +47,7 @@ DH_bits() was added in OpenSSL 1.1.0.

		=head1 COPYRIGHT

		Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
		Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

		Licensed under the OpenSSL license (the "License"). You may not use
		this file except in compliance with the License. You can obtain a copy

doc/man3/DSA_size.pod

+7 −3

Original line number	Diff line number	Diff line
		@@ -2,7 +2,7 @@

		=head1 NAME

		DSA_size, DSA_bits - get DSA signature size or key bits
		DSA_size, DSA_bits, DSA_security_bits - get DSA signature size, key bits or security bits

		=head1 SYNOPSIS

		@@ -10,6 +10,7 @@ DSA_size, DSA_bits - get DSA signature size or key bits

		int DSA_size(const DSA *dsa);
		int DSA_bits(const DSA *dsa);
		int DSA_security_bits(const DSA *dsa);

		=head1 DESCRIPTION

		@@ -22,9 +23,12 @@ B<dsa-E<gt>q> must not be B<NULL>.
		DSA_bits() returns the number of bits in key B<dsa>: this is the number
		of bits in the B<p> parameter.

		DSA_security_bits() returns the number of security bits of the given B<dsa>
		key. See L<BN_security_bits(3)>.

		=head1 RETURN VALUE

		DSA_size() returns the size in bytes.
		DSA_size() returns the signature size in bytes.

		DSA_bits() returns the number of bits in the key.

		@@ -34,7 +38,7 @@ L<DSA_new(3)>, L<DSA_sign(3)>

		=head1 COPYRIGHT

		Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
		Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

		Licensed under the OpenSSL license (the "License"). You may not use
		this file except in compliance with the License. You can obtain a copy

doc/man3/EVP_PKEY_meth_get_count.pod

+2 −2

Original line number	Diff line number	Diff line
		@@ -40,7 +40,7 @@ L<EVP_PKEY_new(3)>

		=head1 COPYRIGHT

		Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
		Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved.

		Licensed under the OpenSSL license (the "License"). You may not use
		this file except in compliance with the License. You can obtain a copy

doc/man3/EVP_SignInit.pod

+8 −1

Original line number	Diff line number	Diff line
		@@ -3,7 +3,8 @@
		=head1 NAME

		EVP_PKEY_size,
		EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing
		EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal,
		EVP_PKEY_security_bits - EVP signing
		functions

		=head1 SYNOPSIS
		@@ -17,6 +18,7 @@ functions
		void EVP_SignInit(EVP_MD_CTX ctx, const EVP_MD type);

		int EVP_PKEY_size(EVP_PKEY *pkey);
		int EVP_PKEY_security_bits(const EVP_PKEY *pkey);

		=head1 DESCRIPTION

		@@ -44,6 +46,9 @@ implementation of digest B<type>.
		EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
		signature returned by EVP_SignFinal() may be smaller.

		EVP_PKEY_security_bits() returns the number of security bits of the given B<pkey>,
		bits of security is defined in NIST SP800-57.

		=head1 RETURN VALUES

		EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
		@@ -53,6 +58,8 @@ EVP_PKEY_size() returns the maximum size of a signature in bytes.

		The error codes can be obtained by L<ERR_get_error(3)>.

		EVP_PKEY_security_bits() returns the number of security bits.

		=head1 NOTES

		The B<EVP> interface to digital signatures should almost always be used in