mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add XXX_security_bits documentation

Browse Source 
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)
This commit is contained in:
Paul Yang 2017-08-09 11:25:19 -04:00 committed by Rich Salz
parent 7a301f08bc
commit 6a2da30347
6 changed files with 99 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
doc/man3/BN_security_bits.pod Normal file
View File

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

24
doc/man3/DH_size.pod
View File

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

10
doc/man3/DSA_size.pod
View File

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

4
doc/man3/EVP_PKEY_meth_get_count.pod
View File

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

9
doc/man3/EVP_SignInit.pod
View File

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

19
doc/man3/RSA_size.pod
View File

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