diff options
author | Paul Yang <yang.yang@baishancloud.com> | 2017-08-09 11:25:19 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-08-09 11:25:19 -0400 |
commit | 6a2da30347d81245dd4841833808621d189a9629 (patch) | |
tree | a03d91c83003e420f2d8c8019632e94edcca2703 /doc | |
parent | 7a301f08bc102179248173426ea15e00fa9211d1 (diff) | |
download | openssl-6a2da30347d81245dd4841833808621d189a9629.tar.gz |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/BN_security_bits.pod | 51 | ||||
-rw-r--r-- | doc/man3/DH_size.pod | 24 | ||||
-rw-r--r-- | doc/man3/DSA_size.pod | 10 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_meth_get_count.pod | 4 | ||||
-rw-r--r-- | doc/man3/EVP_SignInit.pod | 9 | ||||
-rw-r--r-- | doc/man3/RSA_size.pod | 19 |
6 files changed, 99 insertions, 18 deletions
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 <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 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 <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 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 @@ 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 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<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 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<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 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 <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 |