From: Ulf Möller Date: Sun, 30 Jan 2000 22:16:47 +0000 (+0000) Subject: Update docs: corrections, turn buffer docs into manpage, fold SHA1 X-Git-Tag: OpenSSL_0_9_5beta1~152 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=74235cc9ec3123ee7f51211ea054632ca0cf7c91;p=oweals%2Fopenssl.git Update docs: corrections, turn buffer docs into manpage, fold SHA1 pages into one for improved readability, add lhash manpage --- diff --git a/NEWS b/NEWS index 522b620f20..2fe5188ddb 100644 --- a/NEWS +++ b/NEWS @@ -31,6 +31,8 @@ o Memory leak detection now allows applications to add extra information via a per-thread stack o PRNG robustness improved + o Enhanced support for Alpha Linux + o Experimental MacOS support Major changes between OpenSSL 0.9.3 and OpenSSL 0.9.4: diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index 5e3f4ed86e..76f72a34bc 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -228,7 +228,7 @@ RC5 Cipher L, L, L, L, L, L, -L, L, L, +L, L, L, L, L, L, L, L, L, L, L, L, diff --git a/doc/crypto/DH_get_ex_new_index.pod b/doc/crypto/DH_get_ex_new_index.pod index 4604859f08..82e2548bcd 100644 --- a/doc/crypto/DH_get_ex_new_index.pod +++ b/doc/crypto/DH_get_ex_new_index.pod @@ -30,7 +30,7 @@ L, L =head1 HISTORY -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are +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_do_sign.pod b/doc/crypto/DSA_do_sign.pod index 9dcf73de16..a452888413 100644 --- a/doc/crypto/DSA_do_sign.pod +++ b/doc/crypto/DSA_do_sign.pod @@ -36,7 +36,8 @@ L. =head1 SEE ALSO -L, L, L, +L, L, L, +L, L =head1 HISTORY diff --git a/doc/crypto/DSA_dup_DH.pod b/doc/crypto/DSA_dup_DH.pod index 0c15094b56..e3b6c9e61b 100644 --- a/doc/crypto/DSA_dup_DH.pod +++ b/doc/crypto/DSA_dup_DH.pod @@ -8,7 +8,7 @@ DSA_dup_DH - Create a DH structure out of DSA structure #include - DH * DSA_dup_DH(DSA *r); + DH * DSA_dup_DH(DSA *r); =head1 DESCRIPTION @@ -21,6 +21,10 @@ contain its length. DSA_dup_DH() returns the new B structure, and NULL on error. The error codes can be obtained by L. +=head1 NOTE + +Be careful to avoid small subgroup attacks when using this. + =head1 SEE ALSO L, L, L diff --git a/doc/crypto/DSA_generate_parameters.pod b/doc/crypto/DSA_generate_parameters.pod index 04d8c9dff4..b40b941345 100644 --- a/doc/crypto/DSA_generate_parameters.pod +++ b/doc/crypto/DSA_generate_parameters.pod @@ -8,7 +8,7 @@ DSA_generate_parameters - Generate DSA parameters #include - DSA * DSA_generate_parameters(int bits, unsigned char *seed, + DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, int *counter_ret, unsigned long *h_ret, void (*callback)(), void *cb_arg); diff --git a/doc/crypto/DSA_get_ex_new_index.pod b/doc/crypto/DSA_get_ex_new_index.pod index de800ff0db..4612e708ec 100644 --- a/doc/crypto/DSA_get_ex_new_index.pod +++ b/doc/crypto/DSA_get_ex_new_index.pod @@ -30,7 +30,7 @@ L, L =head1 HISTORY -DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are +DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are available since OpenSSL 0.9.5. =cut diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod index c57ebb3146..94b4d4c631 100644 --- a/doc/crypto/DSA_set_method.pod +++ b/doc/crypto/DSA_set_method.pod @@ -48,7 +48,7 @@ the default method is used. struct { /* name of the implementation */ - const char *name; + const char *name; /* sign */ DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, @@ -68,9 +68,9 @@ struct 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); + 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); diff --git a/doc/crypto/DSA_sign.pod b/doc/crypto/DSA_sign.pod index e064fd1c42..f6e60a8ca3 100644 --- a/doc/crypto/DSA_sign.pod +++ b/doc/crypto/DSA_sign.pod @@ -38,6 +38,9 @@ B is the signer's public key. The B parameter is ignored. +The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) +is called. + =head1 RETURN VALUES DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. @@ -52,7 +55,8 @@ Standard, DSS), ANSI X9.30 =head1 SEE ALSO -L, L, L +L, L, L, +L =head1 HISTORY diff --git a/doc/crypto/RAND_load_file.pod b/doc/crypto/RAND_load_file.pod index dd344fbd43..3e75855160 100644 --- a/doc/crypto/RAND_load_file.pod +++ b/doc/crypto/RAND_load_file.pod @@ -8,7 +8,7 @@ RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file #include - char *RAND_file_name(char *buf, int num); + const char *RAND_file_name(char *buf, int num); int RAND_load_file(const char *filename, long max_bytes); diff --git a/doc/crypto/RSA_print.pod b/doc/crypto/RSA_print.pod index 2dd0675d28..ee4ed2a993 100644 --- a/doc/crypto/RSA_print.pod +++ b/doc/crypto/RSA_print.pod @@ -14,6 +14,8 @@ cryptographic parameters #include + int DSAparams_print(BIO *bp, DSA *x); + int DSAparams_print_fp(FILE *fp, DSA *x); int DSA_print(BIO *bp, DSA *x, int offset); int DSA_print_fp(FILE *fp, DSA *x, int offset); @@ -25,7 +27,7 @@ cryptographic parameters =head1 DESCRIPTION A human-readable hexadecimal output of the components of the RSA -key, DSA key or DH parameters is printed to B or B. +key, DSA parameters or key or DH parameters is printed to B or B. The output lines are indented by B spaces. @@ -41,5 +43,6 @@ L, L, L, L RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), DH_print_fp() are available in all versions of SSLeay and OpenSSL. +DSAparams_print() and DSAparams_print_pf() were added in SSLeay 0.8. =cut diff --git a/doc/crypto/SHA1.pod b/doc/crypto/SHA1.pod deleted file mode 100644 index aebcec495c..0000000000 --- a/doc/crypto/SHA1.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -SHA1 - Compute SHA1 hash - -=head1 SYNOPSIS - - #include - - 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 bytes at B and -places it in B (which must have space for SHA_DIGEST_LENGTH == 20 -bytes of output). If B is NULL, the digest is placed in a static -array. - -L 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 - -L, L, L - -=cut diff --git a/doc/crypto/SHA1_Init.pod b/doc/crypto/SHA1_Init.pod deleted file mode 100644 index ecfdd28334..0000000000 --- a/doc/crypto/SHA1_Init.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SHA1_Init, SHA1_Update_SHA1_Final - Compute SHA1 hash - -=head1 SYNOPSIS - - #include - - 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 structure. - -SHA1_Update() can be called repeatedly with chunks of the message to -be hashed (B bytes at B). - -SHA1_Final() places the message digest in B, which must have space -for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B. - -When the entire message is available at one time, L -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 - -L, L, L - -=cut diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod new file mode 100644 index 0000000000..dda8e7b508 --- /dev/null +++ b/doc/crypto/buffer.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - Simple +character arrays structure + +=head1 SYNOPSIS + + #include + + BUF_MEM *BUF_MEM_new(void); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + + char * BUF_strdup(const char *str); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +The library uses the BUF_MEM structure defined in buffer.h: + + typedef struct buf_mem_st + { + int length; /* current number of bytes */ + char *data; + int max; /* size of buffer */ + } BUF_MEM; + +B is the current size of the buffer in bytes, B is the amount of +memory allocated to the buffer. There are three functions which handle these +and one "miscellaneous" function. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B. Any data already in the buffer is preserved if it increases in +size. + +BUF_strdup() copies a null terminated string into a block of allocated +memory and returns a pointer to the allocated block. +Unlike the standard C library strdup() this function uses Malloc() and so +should be used in preference to the standard library strdup() because it can +be used for memory leak checking or replacing the malloc() function. + +The memory allocated from BUF_strdup() should be freed up using the Free() +function. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() returns zero on error or the new size (i.e. B). + +=head1 SEE ALSO + +L + +=head1 HISTORY + +BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all +versions of SSLeay and OpenSSL. BUF_strdup() was addded in SSLeay 0.8. + +=cut diff --git a/doc/crypto/dsa.pod b/doc/crypto/dsa.pod index 2754bb62e3..e5ae42f5a1 100644 --- a/doc/crypto/dsa.pod +++ b/doc/crypto/dsa.pod @@ -92,6 +92,13 @@ Standard, DSS), ANSI X9.30 =head1 SEE ALSO L, L, L, L, -L, L +L, L, L, +L, +L, +L, +L, +L, L, +L, +L =cut diff --git a/doc/crypto/lh_stats.pod b/doc/crypto/lh_stats.pod new file mode 100644 index 0000000000..3eeaa72e52 --- /dev/null +++ b/doc/crypto/lh_stats.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, +lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics + +=head1 SYNOPSIS + + #include + + void lh_stats(LHASH *table, FILE *out); + void lh_node_stats(LHASH *table, FILE *out); + void lh_node_usage_stats(LHASH *table, FILE *out); + + void lh_stats_bio(LHASH *table, BIO *out); + void lh_node_stats_bio(LHASH *table, BIO *out); + void lh_node_usage_stats_bio(LHASH *table, BIO *out); + +=head1 DESCRIPTION + +The B structure records statistics about most aspects of +accessing the hash table. This is mostly a legacy of Eric Young +writing this library for the reasons of implementing what looked like +a nice algorithm rather than for a particular software product. + +lh_stats() prints out statistics on the size of the hash table, how +many entries are in it, and the number and result of calls to the +routines in this library. + +lh_node_stats() prints the number of entries for each 'bucket' in the +hash table. + +lh_node_usage_stats() prints out a short summary of the state of the +hash table. It prints the 'load' and the 'actual load'. The load is +the average number of data items per 'bucket' in the hash table. The +'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. So the 'actual load' is the +average number of searches that will need to find an item in the hash +table, while the 'load' is the average number that will be done to +record a miss. + +lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() +are the same as the above, except that the output goes to a B. + +=head1 RETURN VALUES + +These functions do not return values. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These functions are available in all versions of SSLeay and OpenSSL. + +This manpage is derived from the SSLeay documentation. + +=cut diff --git a/doc/crypto/lhash.pod b/doc/crypto/lhash.pod new file mode 100644 index 0000000000..75f82911a4 --- /dev/null +++ b/doc/crypto/lhash.pod @@ -0,0 +1,155 @@ +=pod + +=head1 NAME + +lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, +lh_doall_arg, lh_error - Dynamic hash table + +=head1 SYNOPSIS + + #include + + LHASH *lh_new(unsigned long (*hash)(/*void *a*/), + int (*compare)(/*void *a,void *b*/)); + void lh_free(LHASH *table); + + void *lh_insert(LHASH *table, void *data); + void *lh_delete(LHASH *table, void *data); + void *lh_retrieve(LHASH *table, void *data); + + void lh_doall(LHASH *table, void (*func)(/*void *b*/)); + void lh_doall_arg(LHASH *table, void (*func)(/*void *a,void *b*/), + void *arg); + + int lh_error(LHASH *table); + +=head1 DESCRIPTION + +This library implements dynamic hash tables. The hash table entries +can be arbitrary structures. Usually they consist of key and value +fields. + +lh_new() creates a new B structure. B takes a pointer to +the structure and returns an unsigned long hash value of its key +field. The hash value is normally truncated to a power of 2, so make +sure that your hash function returns well mixed low order +bits. B takes two arguments, and returns 0 if their keys are +equal, non-zero otherwise. + +lh_free() frees the B structure B. Allocated hash table +entries will not be freed; consider using lh_doall() to deallocate any +remaining entries in the hash table. + +lh_insert() inserts the structure pointed to by B into B
. +If there already is an entry with the same key, the old value is +replaced. Note that lh_insert() stores pointers, the data are not +copied. + +lh_delete() deletes an entry from B
. + +lh_retrieve() looks up an entry in B
. Normally, B is +a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. + +lh_doall() will, for every entry in the hash table, call B with +the data item as parameters. +This function can be quite useful when used as follows: + void cleanup(STUFF *a) + { STUFF_free(a); } + lh_doall(hash,cleanup); + lh_free(hash); +This can be used to free all the entries. lh_free() then cleans up the +'buckets' that point to nothing. When doing this, be careful if you +delete entries from the hash table in B: the table may decrease +in size, moving item that you are currently on down lower in the hash +table. This could cause some entries to be skipped. The best +solution to this problem is to set hash-Edown_load=0 before you +start. This will stop the hash table ever being decreased in size. + +lh_doall_arg() is the same as lh_doall() except that B will +be called with B as the second argument. + +lh_error() can be used to determine if an error occured in the last +operation. lh_error() is a macro. + +=head1 RETURN VALUES + +lh_new() returns B on error, otherwise a pointer to the new +B structure. + +When a hash table entry is replaced, lh_insert() returns the value +being replaced. B is returned on normal operation and on error. + +lh_delete() returns the entry being deleted. B is returned if +there is no such value in the hash table. + +lh_retrieve() returns the hash table entry if it has been found, +B otherwise. + +lh_error() returns 1 if an error occurred in the last operation, 0 +otherwise. + +lh_free(), lh_doall() and lh_doall_arg() return no values. + +=head1 BUGS + +lh_insert() returns B both for success and error. + +=head1 INTERNALS + +The following description is based on the SSLeay documentation: + +The B library implements a hash table described in the +I in 1991. What makes this hash table +different is that as the table fills, the hash table is increased (or +decreased) in size via Realloc(). When a 'resize' is done, instead of +all hashes being redistributed over twice as many 'buckets', one +bucket is split. So when an 'expand' is done, there is only a minimal +cost to redistribute some values. Subsequent inserts will cause more +single 'bucket' redistributions but there will never be a sudden large +cost due to redistributing all the 'buckets'. + +The state for a particular hash table is kept in the B structure. +The decision to increase or decrease the hash table size is made +depending on the 'load' of the hash table. The load is the number of +items in the hash table divided by the size of the hash table. The +default values are as follows. If (hash->up_load E load) =E +expand. if (hash-Edown_load E load) =E contract. The +B has a default value of 1 and B has a default value +of 2. These numbers can be modified by the application by just +playing with the B and B variables. The 'load' is +kept in a form which is multiplied by 256. So +hash-Eup_load=8*256; will cause a load of 8 to be set. + +If you are interested in performance the field to watch is +num_comp_calls. The hash library keeps track of the 'hash' value for +each item so when a lookup is done, the 'hashes' are compared, if +there is a match, then a full compare is done, and +hash-Enum_comp_calls is incremented. If num_comp_calls is not equal +to num_delete plus num_retrieve it means that your hash function is +generating hashes that are the same for different values. It is +probably worth changing your hash function if this is the case because +even if your hash table has 10 items in a 'bucket', it can be searched +with 10 B compares and 10 linked list traverses. This +will be much less expensive that 10 calls to you compare function. + +lh_strhash() is a demo string hashing function: + + unsigned long lh_strhash(const char *c); + +Since the B routines would normally be passed structures, this +routine would not normally be passed to lh_new(), rather it would be +used in the function passed to lh_new(). + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The B library is available in all versions of SSLeay and OpenSSL. +lh_error() was added in SSLeay 0.9.1b. + +This manpage is derived from the SSLeay documentation. + +=cut diff --git a/doc/crypto/rand.pod b/doc/crypto/rand.pod index 0b9ae50c05..0fafe54dd9 100644 --- a/doc/crypto/rand.pod +++ b/doc/crypto/rand.pod @@ -17,7 +17,7 @@ rand - Pseudo-random number generator int RAND_load_file(const char *file,long max_bytes); int RAND_write_file(const char *file); - char *RAND_file_name(char *file,int num); + const char *RAND_file_name(char *file,int num); void RAND_set_rand_method(RAND_METHOD *meth); RAND_METHOD *RAND_get_rand_method(void); diff --git a/doc/crypto/sha.pod b/doc/crypto/sha.pod index c1d40e97dc..e0c1ff2e12 100644 --- a/doc/crypto/sha.pod +++ b/doc/crypto/sha.pod @@ -2,14 +2,14 @@ =head1 NAME -sha - Secure Hash Algorithm +SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm =head1 SYNOPSIS #include unsigned char *SHA1(const unsigned char *d, unsigned long n, - unsigned char *md); + unsigned char *md); void SHA1_Init(SHA_CTX *c); void SHA1_Update(SHA_CTX *c, const unsigned char *data, @@ -21,9 +21,31 @@ sha - Secure Hash Algorithm SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a 160 bit output. +SHA1() computes the SHA-1 message digest of the B +bytes at B and places it in B (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +SHA1_Init() initializes a B structure. + +SHA1_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +SHA1_Final() places the message digest in B, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B. + The predecessor of SHA-1, SHA, is also implemented, but it should be used only when backward compatibility is required. +=head1 RETURN VALUES + +SHA1() returns a pointer to the hash value. + +SHA1_Init(), SHA1_Update() and SHA1_Final() do not return values. + =head1 CONFORMING TO US Federal Information Processing Standard FIPS 180 (Secure Hash @@ -31,6 +53,11 @@ Standard), ANSI X9.30 =head1 SEE ALSO -L, L, L +L + +=head1 HISTORY + +SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all +versions of SSLeay and OpenSSL. =cut diff --git a/doc/openssl.txt b/doc/openssl.txt index 73272509c0..e92f9fd205 100644 --- a/doc/openssl.txt +++ b/doc/openssl.txt @@ -1,54 +1,6 @@ This is some preliminary documentation for OpenSSL. -============================================================================== - BUFFER Library -============================================================================== - -The buffer library handles simple character arrays. Buffers are used for -various purposes in the library, most notably memory BIOs. - -The library uses the BUF_MEM structure defined in buffer.h: - -typedef struct buf_mem_st -{ - int length; /* current number of bytes */ - char *data; - int max; /* size of buffer */ -} BUF_MEM; - -'length' is the current size of the buffer in bytes, 'max' is the amount of -memory allocated to the buffer. There are three functions which handle these -and one "miscellaneous" function. - -BUF_MEM *BUF_MEM_new() - -This allocates a new buffer of zero size. Returns the buffer or NULL on error. - -void BUF_MEM_free(BUF_MEM *a) - -This frees up an already existing buffer. The data is zeroed before freeing -up in case the buffer contains sensitive data. - -int BUF_MEM_grow(BUF_MEM *str, int len) - -This changes the size of an already existing buffer. It returns zero on error -or the new size (i.e. 'len'). Any data already in the buffer is preserved if -it increases in size. - -char * BUF_strdup(char *str) - -This is the previously mentioned strdup function: like the standard library -strdup() it copies a null terminated string into a block of allocated memory -and returns a pointer to the allocated block. - -Unlike the standard C library strdup() this function uses Malloc() and so -should be used in preference to the standard library strdup() because it can -be used for memory leak checking or replacing the malloc() function. - -The memory allocated from BUF_strdup() should be freed up using the Free() -function. - ============================================================================== OpenSSL X509V3 extension configuration ==============================================================================