--- /dev/null
+=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
=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
=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
=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
int DSA_size(const DSA *dsa);
int DSA_bits(const DSA *dsa);
+ int DSA_security_bits(const DSA *dsa);
=head1 DESCRIPTION
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.
=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
=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
=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
=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
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
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
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
=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
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
projects / oweals / openssl.git / commitdiff