Add XXX_security_bits documentation

This is a 'code health' commit to respond to this round of code health
Tuesday...
Reviewed-by: NAndy Polyakov <appro@openssl.org>
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4099)

doc/man3/BN_security_bits.pod

+=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

@@ -2,29 +2,39 @@
 
 =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
 
-#include <openssl/dh.h>
+ #include <openssl/dh.h>
 
-int DH_size(const DH *dh);
+ int DH_size(const DH *dh);
 
-int DH_bits(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

@@ -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,7 +2,7 @@
 
 =head1 NAME
 
-EVP_PKEY_meth_get_count, EVP_PKEY_meth_get0, EVP_PKEY_meth_get0_info - enumeratepublic key methods
+EVP_PKEY_meth_get_count, EVP_PKEY_meth_get0, EVP_PKEY_meth_get0_info - enumerate public key methods
 
 =head1 SYNOPSIS
 
@@ -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

@@ -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

doc/man3/RSA_size.pod

@@ -2,15 +2,17 @@
 
 =head1 NAME
 
-RSA_size, RSA_bits - get RSA modulus size
+RSA_size, RSA_bits, RSA_security_bits - get RSA modulus size or security bits
 
 =head1 SYNOPSIS
 
-#include <openssl/rsa.h>
+ #include <openssl/rsa.h>
 
-int RSA_size(const RSA *rsa);
+ int RSA_size(const RSA *rsa);
 
-int RSA_bits(const RSA *rsa);
+ int RSA_bits(const RSA *rsa);
+
+ int RSA_security_bits(const RSA *rsa)
 
 =head1 DESCRIPTION
 
@@ -22,9 +24,16 @@ RSA_bits() returns the number of significant bits.
 
 B<rsa> and B<rsa-E<gt>n> must not be B<NULL>.
 
+RSA_security_bits() returns the number of security bits of the given B<rsa>
+key. See L<BN_security_bits(3)>.
+
 =head1 RETURN VALUE
 
-The size.
+RSA_size() returns the size of modulus in bytes.
+
+DSA_bits() returns the number of bits in the key.
+
+RSA_security_bits() returns the number of security bits.
 
 =head1 SEE ALSO