generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Document DSA and SHA.

Browse Source 
New function BN_pseudo_rand().
Use BN_prime_checks_size(BN_num_bits(w)) rounds of Miller-Rabin when
generating DSA primes (why not use BN_is_prime()?)
This commit is contained in:
Ulf Möller 2000-01-27 19:31:26 +00:00
parent 0c23524963
commit 38e33cef15
32 changed files with 855 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
CHANGES
View File

@ -2,7 +2,14 @@
OpenSSL CHANGES
_______________
Changes between 0.9.4 and 0.9.5 [xx XXX 1999]
Changes between 0.9.4 and 0.9.5 [xx XXX 2000]
*) Use BN_prime_checks_size(BN_num_bits(w)) rounds of Miller-Rabin when
generating DSA primes.
[Ulf Möller]
*) New function BN_pseudo_rand().
[Ulf Möller]
*) Clean up BN_mod_mul_montgomery(): replace the broken (and unreadable)
bignum version of BN_from_montgomery() with the working code from

19
crypto/bn/bn.h
View File

@ -286,6 +286,25 @@ typedef struct bn_recp_ctx_st
#define BN_prime_checks 0 /* default: select number of iterations
based on the size of the number */
/* number of Miller-Rabin iterations for an error rate of less than 2^-80
* for random 'b'-bit input, b >= 100 (taken from table 4.4 in the Handbook
* of Applied Cryptography [Menezes, van Oorschot, Vanstone; CRC Press 1996];
* original paper: Damgaard, Landrock, Pomerance: Average case error estimates
* for the strong probable prime test. -- Math. Comp. 61 (1993) 177-194) */
#define BN_prime_checks_size(b) ((b) >= 1300 ? 2 : \
(b) >= 850 ? 3 : \
(b) >= 650 ? 4 : \
(b) >= 550 ? 5 : \
(b) >= 450 ? 6 : \
(b) >= 400 ? 7 : \
(b) >= 350 ? 8 : \
(b) >= 300 ? 9 : \
(b) >= 250 ? 12 : \
(b) >= 200 ? 15 : \
(b) >= 150 ? 18 : \
/* b >= 100 */ 27)
#define BN_num_bytes(a) ((BN_num_bits(a)+7)/8)
#define BN_is_word(a,w) (((a)->top == 1) && ((a)->d[0] == (BN_ULONG)(w)))
#define BN_is_zero(a) (((a)->top == 0) || BN_is_word(a,0))

20
crypto/bn/bn_prime.c
View File

@ -68,24 +68,6 @@
*/
#include "bn_prime.h"
/* number of Miller-Rabin iterations for an error rate of less than 2^-80
* for random 'b'-bit input, b >= 100 (taken from table 4.4 in the Handbook
* of Applied Cryptography [Menezes, van Oorschot, Vanstone; CRC Press 1996];
* original paper: Damgaard, Landrock, Pomerance: Average case error estimates
* for the strong probable prime test. -- Math. Comp. 61 (1993) 177-194) */
#define BN_prime_checks_size(b) ((b) >= 1300 ? 2 : \
(b) >= 850 ? 3 : \
(b) >= 650 ? 4 : \
(b) >= 550 ? 5 : \
(b) >= 450 ? 6 : \
(b) >= 400 ? 7 : \
(b) >= 350 ? 8 : \
(b) >= 300 ? 9 : \
(b) >= 250 ? 12 : \
(b) >= 200 ? 15 : \
(b) >= 150 ? 18 : \
/* b >= 100 */ 27)
static int witness(BIGNUM *a, BIGNUM *n, BN_CTX *ctx,BN_CTX *ctx2,
BN_MONT_CTX *mont);
static int probable_prime(BIGNUM *rnd, int bits);
@ -203,7 +185,7 @@ int BN_is_prime(BIGNUM *a, int checks, void (*callback)(int,int,void *),
for (i=0; i<checks; i++)
{
if (!BN_rand(check,BN_num_bits(a)-1,0,0)) goto err;
if (!BN_pseudo_rand(check,BN_num_bits(a)-1,0,0)) goto err;
j=witness(check,a,ctx,ctx2,mont);
if (j == -1) goto err;
if (j)

22
crypto/bn/bn_rand.c
View File

@ -62,7 +62,7 @@
#include "bn_lcl.h"
#include <openssl/rand.h>
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom)
static int bnrand(int pseudorand, BIGNUM *rnd, int bits, int top, int bottom)
{
unsigned char *buf=NULL;
int ret=0,bit,bytes,mask;
@ -83,8 +83,17 @@ int BN_rand(BIGNUM *rnd, int bits, int top, int bottom)
time(&tim);
RAND_add(&tim,sizeof(tim),0);
if (RAND_bytes(buf,(int)bytes) <= 0)
if (pseudorand)
{
if (RAND_pseudo_bytes(buf, bytes) == -1)
goto err;
}
else
{
if (RAND_bytes(buf, bytes) <= 0)
goto err;
}
if (top)
{
if (bit == 0)
@ -116,3 +125,12 @@ err:
return(ret);
}
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom)
{
return bnrand(1, rnd, bits, top, bottom);
}
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom)
{
return bnrand(0, rnd, bits, top, bottom);
}

4
crypto/dsa/dsa.h
View File

@ -182,7 +182,7 @@ DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length);
DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length);
DSA * DSA_generate_parameters(int bits, unsigned char *seed,int seed_len,
int *counter_ret, unsigned long *h_ret,void
(*callback)(),char *cb_arg);
(*callback)(),void *cb_arg);
int DSA_generate_key(DSA *a);
int i2d_DSAPublicKey(DSA *a, unsigned char **pp);
int i2d_DSAPrivateKey(DSA *a, unsigned char **pp);
@ -197,7 +197,7 @@ int DSAparams_print_fp(FILE *fp, DSA *x);
int DSA_print_fp(FILE *bp, DSA *x, int off);
#endif
int DSA_is_prime(BIGNUM *q,void (*callback)(),char *cb_arg);
int DSA_is_prime(BIGNUM *q,void (*callback)(),void *cb_arg);
#ifndef NO_DH
/* Convert DSA structure (key or just parameters) into DH structure

23
crypto/dsa/dsa_gen.c
View File

@ -75,7 +75,7 @@
DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
int *counter_ret, unsigned long *h_ret, void (*callback)(),
char *cb_arg)
void *cb_arg)
{
int ok=0;
unsigned char seed[SHA_DIGEST_LENGTH];
@ -93,6 +93,7 @@ DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
if (bits < 512) bits=512;
bits=(bits+63)/64*64;
if (seed_len < 20) seed_in = NULL;
if ((seed_in != NULL) && (seed_len == 20))
memcpy(seed,seed_in,seed_len);
@ -142,10 +143,10 @@ DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
/* step 3 */
md[0]|=0x80;
md[SHA_DIGEST_LENGTH-1]|=0x01;
if (!BN_bin2bn(md,SHA_DIGEST_LENGTH,q)) abort();
if (!BN_bin2bn(md,SHA_DIGEST_LENGTH,q)) goto err;
/* step 4 */
if (DSA_is_prime(q,callback,cb_arg) > 0) break;
if (BN_is_prime(q,BN_prime_checks,callback,NULL,cb_arg) > 0) break;
/* do a callback call */
/* step 5 */
}
@ -174,7 +175,8 @@ DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
HASH(buf,SHA_DIGEST_LENGTH,md);
/* step 8 */
if (!BN_bin2bn(md,SHA_DIGEST_LENGTH,r0)) abort();
if (!BN_bin2bn(md,SHA_DIGEST_LENGTH,r0))
goto err;
BN_lshift(r0,r0,160*k);
BN_add(W,W,r0);
}
@ -194,7 +196,7 @@ DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
if (BN_cmp(p,test) >= 0)
{
/* step 11 */
if (DSA_is_prime(p,callback,cb_arg) > 0)
if (BN_is_prime(p,BN_prime_checks,callback,NULL,cb_arg) > 0)
goto end;
}
@ -210,7 +212,7 @@ DSA *DSA_generate_parameters(int bits, unsigned char *seed_in, int seed_len,
end:
if (callback != NULL) callback(2,1,cb_arg);
/* We now need to gernerate g */
/* We now need to generate g */
/* Set r0=(p-1)/q */
BN_sub(test,p,BN_value_one());
BN_div(r0,NULL,test,q,ctx);
@ -250,7 +252,7 @@ err:
return(ok?ret:NULL);
}
int DSA_is_prime(BIGNUM *w, void (*callback)(), char *cb_arg)
int DSA_is_prime(BIGNUM *w, void (*callback)(), void *cb_arg)
{
int ok= -1,j,i,n;
BN_CTX *ctx=NULL,*ctx2=NULL;
@ -258,7 +260,7 @@ int DSA_is_prime(BIGNUM *w, void (*callback)(), char *cb_arg)
int a;
BN_MONT_CTX *mont=NULL;
if (!BN_is_bit_set(w,0)) return(0);
if (!BN_is_odd(w)) return(0);
if ((ctx=BN_CTX_new()) == NULL) goto err;
if ((ctx2=BN_CTX_new()) == NULL) goto err;
@ -272,7 +274,7 @@ int DSA_is_prime(BIGNUM *w, void (*callback)(), char *cb_arg)
mont_1= &(ctx2->bn[7]);
/* step 1 */
n=50;
n=BN_prime_checks_size(BN_num_bits(w));
/* step 2 */
if (!BN_sub(w_1,w,BN_value_one())) goto err;
@ -286,7 +288,8 @@ int DSA_is_prime(BIGNUM *w, void (*callback)(), char *cb_arg)
for (i=1; i < n; i++)
{
/* step 3 */
BN_rand(b,BN_num_bits(w)-2/*-1*/,0,0);
if (!BN_pseudo_rand(b,BN_num_bits(w)-2/*-1*/,0,0))
goto err;
/* BN_set_word(b,0x10001L); */
/* step 4 */

2
crypto/dsa/dsatest.c
View File

@ -141,7 +141,7 @@ int main(int argc, char **argv)
CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON);
BIO_printf(bio_err,"test generation of DSA parameters\n");
BIO_printf(bio_err,"expect '.*' followed by 5 lines of '.'s and '+'s\n");
BIO_printf(bio_err,"expect '.*' followed by 3 lines of '.'s and '+'s\n");
dsa=DSA_generate_parameters(512,seed,20,&counter,&h,dsa_cb,
(char *)bio_err);

2
crypto/sha/sha1dgst.c
View File

@ -65,6 +65,8 @@
char *SHA1_version="SHA1" OPENSSL_VERSION_PTEXT;
/* The implementation is in ../md32_common.h */
#include "sha_locl.h"
#endif

2
crypto/sha/sha_dgst.c
View File

@ -65,6 +65,8 @@
char *SHA_version="SHA" OPENSSL_VERSION_PTEXT;
/* The implementation is in ../md32_common.h */
#include "sha_locl.h"
#endif

2
doc/crypto/BN_mod_mul_montgomery.pod
View File

@ -30,7 +30,7 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
These functions implement Montgomery multiplication. They are used
automatically when BN_mod_exp(3) is called with suitable input,
but they may be useful when several operations are to be perfomed
but they may be useful when several operations are to be performed
using the same modulus.
BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.

12
doc/crypto/BN_rand.pod
View File

@ -2,7 +2,7 @@
=head1 NAME
BN_rand - Generate pseudo-random number
BN_rand, BN_rand_pseudo - Generate pseudo-random number
=head1 SYNOPSIS
@ -10,6 +10,8 @@ BN_rand - Generate pseudo-random number
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top,int bottom);
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
@ -18,11 +20,16 @@ two most significant bits of the number will be set to 1, so that the
product of two such random numbers will always have 2*B<bits> length.
If B<bottom> is true, the number will be odd.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
The PRNG must be seeded prior to calling BN_rand().
=head1 RETURN VALUES
BN_rand() returns 1 on success, 0 on error.
BN_rand() and BN_pseudo_rand() return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
@ -33,5 +40,6 @@ L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
=head1 HISTORY
BN_rand() is available in all versions of SSLeay and OpenSSL.
BN_pseudo_rand() was added in OpenSSL 0.9.5.
=cut

5
doc/crypto/DH_generate_parameters.pod
View File

@ -52,6 +52,11 @@ suitable prime.
The parameters generated by DH_generate_parameters() are not to be
used in signature schemes.
=head1 BUGS
If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
a usable generator.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_free(3)|DH_free(3)>

24
doc/crypto/DH_get_ex_new_index.pod
View File

@ -2,33 +2,35 @@
=head1 NAME
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - ...
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
int (*dup_func)(), void (*free_func)());
int DH_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int DH_set_ex_data(DH *d, int idx, char *arg);
int DH_set_ex_data(DH *d, int idx, void *arg);
char *DH_get_ex_data(DH *d, int idx);
=head1 DESCRIPTION
...
=head1 RETURN VALUES
...
These functions handle application specific data in DH
structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
as described in L<RSA_get_ex_new_index(3)>.
=head1 SEE ALSO
...
L<RSA_get_ex_new_index()|RSA_get_ex_new_index()>, L<dh(3)|dh(3)>
=head1 HISTORY
...
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are
available since OpenSSL 0.9.5.
=cut

2
doc/crypto/DH_new.pod
View File

@ -10,7 +10,7 @@ DH_new, DH_free - allocate and free DH objects
DH* DH_new(void);
void DH_free(DH *rsa);
void DH_free(DH *dh);
=head1 DESCRIPTION

39
doc/crypto/DSA_SIG_new.pod Normal file
View File

@ -0,0 +1,39 @@
=pod
=head1 NAME
DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
=head1 DESCRIPTION
DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure.
DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
values are erased before the memory is returned to the system.
=head1 RETURN VALUES
If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_SIG_free() returns no value.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_do_sign(3)|DSA_do_sign(3)>
=head1 HISTORY
DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.
=cut

46
doc/crypto/DSA_do_sign.pod Normal file
View File

@ -0,0 +1,46 @@
=pod
=head1 NAME
DSA_do_sign, DSA_do_verify - Raw DSA signature operations
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
int DSA_do_verify(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
=head1 DESCRIPTION
DSA_do_sign() computes a digital signature on the B<len> byte message
digest B<dgst> using the private key B<dsa> and returns it in a
newly allocated B<DSA_SIG> structure.
L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part
of the signing operation in case signature generation is
time-critical.
DSA_do_verify() verifies that the signature B<sig> matches a given
message digest B<dgst> of size B<len>. B<dsa> is the signer's public
key.
=head1 RETURN VALUES
DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
returns 1 for a valid signature, 0 for an incorrect signature and -1
on error. The error codes can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_SIG_new(3)|DSA_SIG_new(3)>,
L<DSA_sign(3)|DSA_sign(3)>
=head1 HISTORY
DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.
=cut

32
doc/crypto/DSA_dup_DH.pod Normal file
View File

@ -0,0 +1,32 @@
=pod
=head1 NAME
DSA_dup_DH - Create a DH structure out of DSA structure
=head1 SYNOPSIS
#include <openssl/dsa.h>
DH * DSA_dup_DH(DSA *r);
=head1 DESCRIPTION
DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
is lost during that conversion, but the resulting DH parameters
contain its length.
=head1 RETURN VALUE
DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>
=head1 HISTORY
DSA_dup_DH() was added in OpenSSL 0.9.4.
=cut

33
doc/crypto/DSA_generate_key.pod Normal file
View File

@ -0,0 +1,33 @@
=pod
=head1 NAME
DSA_generate_key - Generate DSA key pair
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_generate_key(DSA *a);
=head1 DESCRIPTION
DSA_generate_key() expects B<a> to contain DSA parameters. It generates
a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
The PRNG must be seeded prior to calling DSA_generate_key().
=head1 RETURN VALUE
DSA_generate_key() returns 1 on success, 0 otherwise.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>
=head1 HISTORY
DSA_generate_key() is available since SSLeay 0.8.
=cut

94
doc/crypto/DSA_generate_parameters.pod Normal file
View File

@ -0,0 +1,94 @@
=pod
=head1 NAME
DSA_generate_parameters - Generate DSA parameters
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA * DSA_generate_parameters(int bits, unsigned char *seed,
int seed_len, int *counter_ret, unsigned long *h_ret,
void (*callback)(), void *cb_arg);
=head1 DESCRIPTION
DSA_generate_parameters() generates primes p and q and a generator g
for use in the DSA.
B<bits> is the length of the prime to be generated; the DSS allows a
maximum of 1024 bits.
If B<seed> is NULL or B<seed_len> E<lt> 20, the primes will be
generated at random. Otherwise, the seed is used to generate
them. If the given seed does not yield a prime q, a new random
seed is chosen and placed at B<seed>.
DSA_generate_parameters() places the iteration count in
*B<counter_ret> and a counter used for finding a generator in
*B<h_ret>, unless these are NULL.
A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
called as follows:
=over 4
=item *
When the the m-th candidate for q is generated, B<callback(0, m,
cb_arg)> is called.
=item *
B<callback(1, j++, cb_arg)> is called in the inner loop of the
Miller-Rabin primality test.
=item *
When a prime q has been found, B<callback(2, 0, cb_arg)> and
B<callback(3, 0, cb_arg)> are called.
=item *
While candidates for p are being tested, B<callback(1, j++, cb_arg)>
is called in the inner loop of the Miller-Rabin primality test, then
B<callback(0, counter, cb_arg)> is called when the next candidate
is chosen.
=item *
When p has been found, B<callback(2, 1, cb_arg)> is called.
=item *
When the generator has been found, B<callback(3, 1, cb_arg)> is called.
=back
=head1 RETURN VALUE
DSA_generate_parameters() returns a pointer to the DSA structure, or
NULL if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 BUGS
The deterministic generation of p does not follow the NIST algorithm:
r0 is SHA1(s+k+1), but should be SHA1(s+j+k) with j_0=2,
j_counter=j_counter-1 + n + 1.
Seed lengths E<gt> 20 are not supported.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>,
L<DSA_free(3)|DSA_free(3)>
=head1 HISTORY
DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg>
argument was added in SSLeay 0.9.0.
=cut

36
doc/crypto/DSA_get_ex_new_index.pod Normal file
View File

@ -0,0 +1,36 @@
=pod
=head1 NAME
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures
=head1 SYNOPSIS
#include <openssl/DSA.h>
int DSA_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int DSA_set_ex_data(DSA *d, int idx, void *arg);
char *DSA_get_ex_data(DSA *d, int idx);
=head1 DESCRIPTION
These functions handle application specific data in DSA
structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
as described in L<RSA_get_ex_new_index(3)>.
=head1 SEE ALSO
L<RSA_get_ex_new_index()|RSA_get_ex_new_index()>, L<dsa(3)|dsa(3)>
=head1 HISTORY
DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are
available since OpenSSL 0.9.5.
=cut

41
doc/crypto/DSA_new.pod Normal file
View File

@ -0,0 +1,41 @@
=pod
=head1 NAME
DSA_new, DSA_free - allocate and free DSA objects
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA* DSA_new(void);
void DSA_free(DSA *dsa);
=head1 DESCRIPTION
DSA_new() allocates and initializes a B<DSA> structure.
DSA_free() frees the B<DSA> structure and its components. The values are
erased before the memory is returned to the system.
=head1 RETURN VALUES
If the allocation fails, DSA_new() returns B<NULL> and sets an error
code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_free() returns no value.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>,
L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
L<DSA_generate_key(3)|DSA_generate_key(3)>
=head1 HISTORY
DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL.
=cut

111
doc/crypto/DSA_set_method.pod Normal file
View File

@ -0,0 +1,111 @@
=pod
=head1 NAME
DSA_set_default_method, DSA_get_default_method, DSA_set_method,
DSA_new_method, DSA_OpenSSL - Select RSA method
=head1 SYNOPSIS
#include <openssl/DSA.h>
void DSA_set_default_method(DSA_METHOD *meth);
DSA_METHOD *DSA_get_default_method(void);
DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth);
DSA *DSA_new_method(DSA_METHOD *meth);
DSA_METHOD *DSA_OpenSSL(void);
=head1 DESCRIPTION
A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used.
Initially, the default is to use the OpenSSL internal implementation.
DSA_OpenSSL() returns a pointer to that method.
DSA_set_default_method() makes B<meth> the default method for all B<DSA>
structures created later.
DSA_get_default_method() returns a pointer to the current default
method.
DSA_set_method() selects B<meth> for all operations using the structure B<DSA>.
DSA_get_method() returns a pointer to the method currently selected
for B<DSA>.
DSA_new_method() allocates and initializes a B<DSA> structure so that
B<method> will be used for the DSA operations. If B<method> is B<NULL>,
the default method is used.
=head1 THE DSA_METHOD STRUCTURE
struct
{
/* name of the implementation */
const char *name;
/* sign */
DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
DSA *dsa);
/* pre-compute k^-1 and r */
int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
BIGNUM **rp);
/* verify */
int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
/* compute rr = a1^p1 * a2^p2 mod m. May be NULL */
int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
BN_CTX *ctx, BN_MONT_CTX *in_mont);
/* compute r = a ^ p mod m. May be NULL */
int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx,
BN_MONT_CTX *m_ctx);
/* called at DSA_new */
int (*init)(DSA *DSA);
/* called at DSA_free */
int (*finish)(DSA *DSA);
int flags;
char *app_data; /* ?? */
} DSA_METHOD;
=head1 RETURN VALUES
DSA_OpenSSL(), DSA_get_default_method() and DSA_get_method() return
pointers to the respective B<DSA_METHOD>s.
DSA_set_default_method() returns no value.
DSA_set_method() returns a pointer to the B<DSA_METHOD> previously
associated with B<dsa>.
DSA_new_method() returns B<NULL> and sets an error code that can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
fails. Otherwise it returns a pointer to the newly allocated
structure.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
=head1 HISTORY
DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
=cut

62
doc/crypto/DSA_sign.pod Normal file
View File

@ -0,0 +1,62 @@
=pod
=head1 NAME
DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_sign(int type, const unsigned char *dgst, int len,
unsigned char *sigret, unsigned int *siglen, DSA *dsa);
int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
BIGNUM **rp);
int DSA_verify(int type, const unsigned char *dgst, int len,
unsigned char *sigbuf, int siglen, DSA *dsa);
=head1 DESCRIPTION
DSA_sign() computes a digital signature on the B<len> byte message
digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
encoding at B<sigret>. The length of the signature is places in
*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
DSA_sign_setup() may be used to precompute part of the signing
operation in case signature generation is time-critical. It expects
B<dsa> to contain DSA parameters. It places the precomputed values
in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
B<ctx> is a pre-allocated B<BN_CTX> or NULL.
DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
matches a given message digest B<dgst> of size B<len>.
B<dsa> is the signer's public key.
The B<type> parameter is ignored.
=head1 RETURN VALUES
DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
DSA_verify() returns 1 for a valid signature, 0 for an incorrect
signature and -1 on error. The error codes can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 CONFORMING TO
US Federal Information Processing Standard FIPS 186 (Digital Signature
Standard, DSS), ANSI X9.30
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_do_sign(3)|DSA_do_sign(3)>
=head1 HISTORY
DSA_sign() and DSA_verify() are available in all versions of SSLeay.
DSA_sign_setup() was added in SSLeay 0.8.
=cut

33
doc/crypto/DSA_size.pod Normal file
View File

@ -0,0 +1,33 @@
=pod
=head1 NAME
DSA_size - Get DSA signature size
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_size(DSA *dsa);
=head1 DESCRIPTION
This function returns the size of an ASN.1 encoded DSA signature in
bytes. It can be used to determine how much memory must be allocated
for a DSA signature.
B<dsa-E<gt>q> must not be B<NULL>.
=head1 RETURN VALUE
The size in bytes.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)>
=head1 HISTORY
DSA_size() is available in all versions of SSLeay and OpenSSL.
=cut

5
doc/crypto/RSA_get_ex_new_index.pod
View File

@ -2,7 +2,7 @@
=head1 NAME
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures.
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures
=head1 SYNOPSIS
@ -22,6 +22,7 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specifi
void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
@ -115,7 +116,7 @@ L<rsa(3)|rsa(3)>
=head1 HISTORY
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data are
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are
available since SSLeay 0.9.0.
=cut

36
doc/crypto/SHA1.pod Normal file
View File

@ -0,0 +1,36 @@
=pod
=head1 NAME
SHA1 - Compute SHA1 hash
=head1 SYNOPSIS
#include <openssl/sha.h>
unsigned char *SHA1(const unsigned char *d, unsigned long n,
unsigned char *md);
=head1 DESCRIPTION
SHA1() computes the SHA-1 message digest of the B<n> bytes at B<d> and
places it in B<md> (which must have space for SHA_DIGEST_LENGTH == 20
bytes of output). If B<md> is NULL, the digest is placed in a static
array.
L<SHA1_Init(3)|SHA1_Init(3)> may be used if the message is not completely
stored in memory.
=head1 RETURN VALUE
SHA1() returns a pointer to the hash value.
=head1 HISTORY
SHA1() is available in all versions of SSLeay and OpenSSL.
=head1 SEE ALSO
sha(3), ripemd(3), SHA1_Init(3)
=cut

42
doc/crypto/SHA1_Init.pod Normal file
View File

@ -0,0 +1,42 @@
=pod
=head1 NAME
SHA1_Init, SHA1_Update_SHA1_Final - Compute SHA1 hash
=head1 SYNOPSIS
#include <openssl/sha.h>
void SHA1_Init(SHA_CTX *c);
void SHA1_Update(SHA_CTX *c, const unsigned char *data,
unsigned long len);
void SHA1_Final(unsigned char *md, SHA_CTX *c);
=head1 DESCRIPTION
SHA1_Init() initializes a B<SHA_CTX> structure.
SHA1_Update() can be called repeatedly with chunks of the message to
be hashed (B<len> bytes at B<data>).
SHA1_Final() places the message digest in B<md>, which must have space
for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>.
When the entire message is available at one time, L<SHA1(3)|SHA(1)>
can be used.
=head1 RETURN VALUES
SHA1_Init(), SHA1_Update() and SHA1_Final() do not return values.
=head1 HISTORY
SHA1_Init(), SHA1_Update() and SHA1_Final()are available in all
versions of SSLeay and OpenSSL.
=head1 SEE ALSO
sha(3), ripemd(3), SHA1(3)
=cut

1
doc/crypto/bn.pod
View File

@ -59,6 +59,7 @@ bn - Multiprecision integer arithmetics
unsigned long BN_get_word(BIGNUM *a);
int BN_rand(BIGNUM *rnd, int bits, int top,int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top,int bottom);
BIGNUM *BN_generate_prime(BIGNUM *ret,int bits,int safe,BIGNUM *add,
BIGNUM *rem,void (*callback)(int,int,void *),void *cb_arg);

22
doc/crypto/dh.pod
View File

@ -8,22 +8,11 @@ dh - Diffie-Hellman key agreement
#include <openssl/dh.h>
void DH_set_default_method(DH_METHOD *meth);
DH_METHOD *DH_get_default_method(void);
DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth);
DH *DH_new_method(DH_METHOD *meth);
DH_METHOD *DH_OpenSSL(void);
DH * DH_new(void);
void DH_free(DH *dh);
int DH_size(DH *dh);
int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
int (*dup_func)(), void (*free_func)());
int DH_set_ex_data(DH *d, int idx, char *arg);
char *DH_get_ex_data(DH *d, int idx);
DH * DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
int DH_check(DH *dh, int *codes);
@ -31,6 +20,17 @@ dh - Diffie-Hellman key agreement
int DH_generate_key(DH *dh);
int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
void DH_set_default_method(DH_METHOD *meth);
DH_METHOD *DH_get_default_method(void);
DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth);
DH *DH_new_method(DH_METHOD *meth);
DH_METHOD *DH_OpenSSL(void);
int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
int (*dup_func)(), void (*free_func)());
int DH_set_ex_data(DH *d, int idx, char *arg);
char *DH_get_ex_data(DH *d, int idx);
DH * d2i_DHparams(DH **a, unsigned char **pp, long length);
int i2d_DHparams(DH *a, unsigned char **pp);

95
doc/crypto/dsa.pod Normal file
View File

@ -0,0 +1,95 @@
=pod
=head1 NAME
dsa - Digital Signature Algorithm
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA * DSA_new(void);
void DSA_free(DSA *dsa);
int DSA_size(DSA *dsa);
DSA * DSA_generate_parameters(int bits, unsigned char *seed,
int seed_len, int *counter_ret, unsigned long *h_ret,
void (*callback)(), void *cb_arg);
DH * DSA_dup_DH(DSA *r);
int DSA_generate_key(DSA *dsa);
int DSA_sign(int dummy, const unsigned char *dgst, int len,
unsigned char *sigret, unsigned int *siglen, DSA *dsa);
int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
BIGNUM **rp);
int DSA_verify(int dummy, const unsigned char *dgst, int len,
unsigned char *sigbuf, int siglen, DSA *dsa);
void DSA_set_default_method(DSA_METHOD *meth);
DSA_METHOD *DSA_get_default_method(void);
DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth);
DSA *DSA_new_method(DSA_METHOD *meth);
DSA_METHOD *DSA_OpenSSL(void);
int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
int (*dup_func)(), void (*free_func)());
int DSA_set_ex_data(DSA *d, int idx, char *arg);
char *DSA_get_ex_data(DSA *d, int idx);
DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
int i2d_DSA_SIG(DSA_SIG *a, unsigned char **pp);
DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length);
DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
int DSA_do_verify(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length);
DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length);
DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length);
int i2d_DSAPublicKey(DSA *a, unsigned char **pp);
int i2d_DSAPrivateKey(DSA *a, unsigned char **pp);
int i2d_DSAparams(DSA *a,unsigned char **pp);
int DSAparams_print(BIO *bp, DSA *x);
int DSAparams_print_fp(FILE *fp, DSA *x);
int DSA_print(BIO *bp, DSA *x, int off);
int DSA_print_fp(FILE *bp, DSA *x, int off);
=head1 DESCRIPTION
These functions implement the Digital Signature Algorithm (DSA). The
generation of shared DSA parameters is described in
L<DSA_generate_parameters(3)>; L<DSA_generate_key(3)> describes how to
generate a signature key. Signature generation and verification are
described in L<DSA_sign(3)>.
The B<DSA> structure consists of several BIGNUM components.
struct
{
BIGNUM *p; // prime number (public)
BIGNUM *q; // 160-bit subprime, q | p-1 (public)
BIGNUM *g; // generator of subgroup (public)
BIGNUM *priv_key; // private key x
BIGNUM *pub_key; // public key y = g^x
// ...
}
DSA;
In public keys, B<priv_key> is NULL.
=head1 CONFORMING TO
US Federal Information Processing Standard FIPS 186 (Digital Signature
Standard, DSS), ANSI X9.30
=head1 SEE ALSO
bn(3), dh(3), err(3), rand(3), rsa(3), sha(3)
=cut

4
doc/crypto/rsa.pod
View File

@ -110,6 +110,10 @@ B<NULL>.
B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private keys, but the
RSA operations are much faster when these values are available.
=head1 CONFORMING TO
SSL, PKCS #1 v2.0
=head1 PATENTS
RSA is covered by a US patent which expires in September 2000.

36
doc/crypto/sha.pod Normal file
View File

@ -0,0 +1,36 @@
=pod
=head1 NAME
sha - Secure Hash Algorithm
=head1 SYNOPSIS
#include <openssl/sha.h>
unsigned char *SHA1(const unsigned char *d, unsigned long n,
unsigned char *md);
void SHA1_Init(SHA_CTX *c);
void SHA1_Update(SHA_CTX *c, const unsigned char *data,
unsigned long len);
void SHA1_Final(unsigned char *md, SHA_CTX *c);
=head1 DESCRIPTION
SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
160 bit output.
The predecessor of SHA-1, SHA, is also implemented, but it should be
used only when backward compatibility is required.
=head1 CONFORMING TO
US Federal Information Processing Standard FIPS 180 (Secure Hash
Standard), ANSI X9.30
=head1 SEE ALSO
ripemd(3), SHA1(3), SHA1_Init(3)
=cut