From 6a2da30347d81245dd4841833808621d189a9629 Mon Sep 17 00:00:00 2001 From: Paul Yang Date: Wed, 9 Aug 2017 11:25:19 -0400 Subject: [PATCH] Add XXX_security_bits documentation This is a 'code health' commit to respond to this round of code health Tuesday... Reviewed-by: Andy Polyakov Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/4099) --- 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 0000000000..1aed85a71a --- /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 + + 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 and B are used to decide the bits of security, where +B is the size of the public key and B is the size of the private +key. For IFC, e.g., RSA, only B 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, L, L + +=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. + +=cut diff --git a/doc/man3/DH_size.pod b/doc/man3/DH_size.pod index c118bf3234..2421558d1f 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 + #include -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_bits() returns the number of significant bits. B and Bp> must not be B. +DH_security_bits() returns the number of security bits of the given B +key. See L. + =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 abf8a458b6..d48f24ed6e 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 @@ Bq> must not be B. DSA_bits() returns the number of bits in key B: this is the number of bits in the B

parameter. +DSA_security_bits() returns the number of security bits of the given B +key. See L. + =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, L =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 9cf69ddbf8..4d2eab50fe 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 =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 c40da1ea3a..987526c4e4 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. 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, +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. +EVP_PKEY_security_bits() returns the number of security bits. + =head1 NOTES The B 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 eb6e481361..58da72a4a3 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 + #include -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 and Bn> must not be B. +RSA_security_bits() returns the number of security bits of the given B +key. See L. + =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 -- GitLab