[openssl-commits] [openssl] master update
Rich Salz
rsalz at openssl.org
Wed Aug 9 15:26:47 UTC 2017
The branch master has been updated
via 6a2da30347d81245dd4841833808621d189a9629 (commit)
from 7a301f08bc102179248173426ea15e00fa9211d1 (commit)
- Log -----------------------------------------------------------------
commit 6a2da30347d81245dd4841833808621d189a9629
Author: Paul Yang <yang.yang at baishancloud.com>
Date: Wed Aug 9 11:25:19 2017 -0400
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 at openssl.org>
Reviewed-by: Rich Salz <rsalz at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4099)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/BN_security_bits.pod | 51 ++++++++++++++++++++++++++++++++++++
doc/man3/DH_size.pod | 24 ++++++++++++-----
doc/man3/DSA_size.pod | 10 ++++---
doc/man3/EVP_PKEY_meth_get_count.pod | 4 +--
doc/man3/EVP_SignInit.pod | 9 ++++++-
doc/man3/RSA_size.pod | 19 ++++++++++----
6 files changed, 99 insertions(+), 18 deletions(-)
create mode 100644 doc/man3/BN_security_bits.pod
diff --git a/doc/man3/BN_security_bits.pod b/doc/man3/BN_security_bits.pod
new file mode 100644
index 0000000..1aed85a
--- /dev/null
+++ b/doc/man3/BN_security_bits.pod
@@ -0,0 +1,51 @@
+=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
diff --git a/doc/man3/DH_size.pod b/doc/man3/DH_size.pod
index c118bf3..2421558 100644
--- a/doc/man3/DH_size.pod
+++ b/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
diff --git a/doc/man3/DSA_size.pod b/doc/man3/DSA_size.pod
index abf8a45..d48f24e 100644
--- a/doc/man3/DSA_size.pod
+++ b/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
diff --git a/doc/man3/EVP_PKEY_meth_get_count.pod b/doc/man3/EVP_PKEY_meth_get_count.pod
index 9cf69dd..4d2eab5 100644
--- a/doc/man3/EVP_PKEY_meth_get_count.pod
+++ b/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
diff --git a/doc/man3/EVP_SignInit.pod b/doc/man3/EVP_SignInit.pod
index c40da1e..987526c 100644
--- a/doc/man3/EVP_SignInit.pod
+++ b/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
diff --git a/doc/man3/RSA_size.pod b/doc/man3/RSA_size.pod
index eb6e481..58da72a 100644
--- a/doc/man3/RSA_size.pod
+++ b/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
More information about the openssl-commits
mailing list