Document DSA and SHA. 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()?)
diff --git a/CHANGES b/CHANGES index ced9abf..6ef0317 100644 --- a/CHANGES +++ b/CHANGES
@@ -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
diff --git a/crypto/bn/bn.h b/crypto/bn/bn.h index 9c92d76..aade579 100644 --- a/crypto/bn/bn.h +++ b/crypto/bn/bn.h
@@ -286,6 +286,25 @@ #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))
diff --git a/crypto/bn/bn_prime.c b/crypto/bn/bn_prime.c index e22851d..84f0699 100644 --- a/crypto/bn/bn_prime.c +++ b/crypto/bn/bn_prime.c
@@ -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 @@ 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)
diff --git a/crypto/bn/bn_rand.c b/crypto/bn/bn_rand.c index b567b43..dd6f6c9 100644 --- a/crypto/bn/bn_rand.c +++ b/crypto/bn/bn_rand.c
@@ -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 @@ time(&tim); RAND_add(&tim,sizeof(tim),0); - if (RAND_bytes(buf,(int)bytes) <= 0) - goto err; + 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 @@ 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); + }
diff --git a/crypto/dsa/dsa.h b/crypto/dsa/dsa.h index a68d3f6..3da104b 100644 --- a/crypto/dsa/dsa.h +++ b/crypto/dsa/dsa.h
@@ -182,7 +182,7 @@ 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 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
diff --git a/crypto/dsa/dsa_gen.c b/crypto/dsa/dsa_gen.c index 57435a9..5df9132 100644 --- a/crypto/dsa/dsa_gen.c +++ b/crypto/dsa/dsa_gen.c
@@ -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 @@ 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 @@ /* 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 @@ 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 @@ 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 @@ 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 @@ 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 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 @@ 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 @@ 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 */
diff --git a/crypto/dsa/dsatest.c b/crypto/dsa/dsatest.c index 220f71c..a30dae6 100644 --- a/crypto/dsa/dsatest.c +++ b/crypto/dsa/dsatest.c
@@ -141,7 +141,7 @@ 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);
diff --git a/crypto/sha/sha1dgst.c b/crypto/sha/sha1dgst.c index 141daf0..dc00812 100644 --- a/crypto/sha/sha1dgst.c +++ b/crypto/sha/sha1dgst.c
@@ -65,6 +65,8 @@ char *SHA1_version="SHA1" OPENSSL_VERSION_PTEXT; +/* The implementation is in ../md32_common.h */ + #include "sha_locl.h" #endif
diff --git a/crypto/sha/sha_dgst.c b/crypto/sha/sha_dgst.c index 81bce0c..1aade35 100644 --- a/crypto/sha/sha_dgst.c +++ b/crypto/sha/sha_dgst.c
@@ -65,6 +65,8 @@ char *SHA_version="SHA" OPENSSL_VERSION_PTEXT; +/* The implementation is in ../md32_common.h */ + #include "sha_locl.h" #endif
diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod index dacd83f..825a29f 100644 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ b/doc/crypto/BN_mod_mul_montgomery.pod
@@ -30,7 +30,7 @@ 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.
diff --git a/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod index 0f69268..47991b1 100644 --- a/doc/crypto/BN_rand.pod +++ b/doc/crypto/BN_rand.pod
@@ -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 @@ 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 @@ 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 @@ =head1 HISTORY BN_rand() is available in all versions of SSLeay and OpenSSL. +BN_pseudo_rand() was added in OpenSSL 0.9.5. =cut
diff --git a/doc/crypto/DH_generate_parameters.pod b/doc/crypto/DH_generate_parameters.pod index 137b387..8102e53 100644 --- a/doc/crypto/DH_generate_parameters.pod +++ b/doc/crypto/DH_generate_parameters.pod
@@ -52,6 +52,11 @@ 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)>
diff --git a/doc/crypto/DH_get_ex_new_index.pod b/doc/crypto/DH_get_ex_new_index.pod index d52181e..4604859 100644 --- a/doc/crypto/DH_get_ex_new_index.pod +++ b/doc/crypto/DH_get_ex_new_index.pod
@@ -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
diff --git a/doc/crypto/DH_new.pod b/doc/crypto/DH_new.pod index 9116b9f..64624b9 100644 --- a/doc/crypto/DH_new.pod +++ b/doc/crypto/DH_new.pod
@@ -10,7 +10,7 @@ DH* DH_new(void); - void DH_free(DH *rsa); + void DH_free(DH *dh); =head1 DESCRIPTION
diff --git a/doc/crypto/DSA_SIG_new.pod b/doc/crypto/DSA_SIG_new.pod new file mode 100644 index 0000000..6716555 --- /dev/null +++ b/doc/crypto/DSA_SIG_new.pod
@@ -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
diff --git a/doc/crypto/DSA_do_sign.pod b/doc/crypto/DSA_do_sign.pod new file mode 100644 index 0000000..9dcf73d --- /dev/null +++ b/doc/crypto/DSA_do_sign.pod
@@ -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
diff --git a/doc/crypto/DSA_dup_DH.pod b/doc/crypto/DSA_dup_DH.pod new file mode 100644 index 0000000..0c15094 --- /dev/null +++ b/doc/crypto/DSA_dup_DH.pod
@@ -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
diff --git a/doc/crypto/DSA_generate_key.pod b/doc/crypto/DSA_generate_key.pod new file mode 100644 index 0000000..e253501 --- /dev/null +++ b/doc/crypto/DSA_generate_key.pod
@@ -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
diff --git a/doc/crypto/DSA_generate_parameters.pod b/doc/crypto/DSA_generate_parameters.pod new file mode 100644 index 0000000..1058c5e --- /dev/null +++ b/doc/crypto/DSA_generate_parameters.pod
@@ -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
diff --git a/doc/crypto/DSA_get_ex_new_index.pod b/doc/crypto/DSA_get_ex_new_index.pod new file mode 100644 index 0000000..0854567 --- /dev/null +++ b/doc/crypto/DSA_get_ex_new_index.pod
@@ -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
diff --git a/doc/crypto/DSA_new.pod b/doc/crypto/DSA_new.pod new file mode 100644 index 0000000..7dde544 --- /dev/null +++ b/doc/crypto/DSA_new.pod
@@ -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
diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod new file mode 100644 index 0000000..c57ebb3 --- /dev/null +++ b/doc/crypto/DSA_set_method.pod
@@ -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
diff --git a/doc/crypto/DSA_sign.pod b/doc/crypto/DSA_sign.pod new file mode 100644 index 0000000..e064fd1 --- /dev/null +++ b/doc/crypto/DSA_sign.pod
@@ -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
diff --git a/doc/crypto/DSA_size.pod b/doc/crypto/DSA_size.pod new file mode 100644 index 0000000..551d1e2 --- /dev/null +++ b/doc/crypto/DSA_size.pod
@@ -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
diff --git a/doc/crypto/RSA_get_ex_new_index.pod b/doc/crypto/RSA_get_ex_new_index.pod index 2d3d0a7..d0267a2 100644 --- a/doc/crypto/RSA_get_ex_new_index.pod +++ b/doc/crypto/RSA_get_ex_new_index.pod
@@ -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 @@ -13,7 +13,7 @@ CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - int RSA_set_ex_data(RSA *r,int idx,void *arg); + int RSA_set_ex_data(RSA *r, int idx, void *arg); void *RSA_get_ex_data(RSA *r, int idx); @@ -22,6 +22,7 @@ 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 @@ =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
diff --git a/doc/crypto/SHA1.pod b/doc/crypto/SHA1.pod new file mode 100644 index 0000000..30fc6c9 --- /dev/null +++ b/doc/crypto/SHA1.pod
@@ -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
diff --git a/doc/crypto/SHA1_Init.pod b/doc/crypto/SHA1_Init.pod new file mode 100644 index 0000000..258f189 --- /dev/null +++ b/doc/crypto/SHA1_Init.pod
@@ -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
diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod index ca48019..3d4840f 100644 --- a/doc/crypto/bn.pod +++ b/doc/crypto/bn.pod
@@ -59,6 +59,7 @@ 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);
diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod index ce32555..0a9b7c0 100644 --- a/doc/crypto/dh.pod +++ b/doc/crypto/dh.pod
@@ -8,22 +8,11 @@ #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 @@ 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);
diff --git a/doc/crypto/dsa.pod b/doc/crypto/dsa.pod new file mode 100644 index 0000000..f0abfc0 --- /dev/null +++ b/doc/crypto/dsa.pod
@@ -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
diff --git a/doc/crypto/rsa.pod b/doc/crypto/rsa.pod index 4c48bc4..3c600bc 100644 --- a/doc/crypto/rsa.pod +++ b/doc/crypto/rsa.pod
@@ -110,6 +110,10 @@ 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.
diff --git a/doc/crypto/sha.pod b/doc/crypto/sha.pod new file mode 100644 index 0000000..6585256 --- /dev/null +++ b/doc/crypto/sha.pod
@@ -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