From d87f13d29bdce02ae37ef5da3fb9e0227724e57b Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 12 Nov 2015 00:55:49 +0000 Subject: Convert the handful of manuals that had imaginary names, give them names that really exist. This also helps jmc@'s ongoing work on improving NAME sections. --- src/lib/libssl/src/doc/crypto/bn_internal.pod | 238 ---------------- .../libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod | 58 ---- src/lib/libssl/src/doc/crypto/ecdsa.pod | 205 -------------- src/lib/libssl/src/doc/crypto/lhash.pod | 303 --------------------- src/lib/libssl/src/doc/crypto/ui.pod | 194 ------------- src/lib/libssl/src/doc/crypto/ui_compat.pod | 57 ---- 6 files changed, 1055 deletions(-) delete mode 100644 src/lib/libssl/src/doc/crypto/bn_internal.pod delete mode 100644 src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ecdsa.pod delete mode 100644 src/lib/libssl/src/doc/crypto/lhash.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ui.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ui_compat.pod (limited to 'src/lib/libssl') diff --git a/src/lib/libssl/src/doc/crypto/bn_internal.pod b/src/lib/libssl/src/doc/crypto/bn_internal.pod deleted file mode 100644 index 9c59ed623b..0000000000 --- a/src/lib/libssl/src/doc/crypto/bn_internal.pod +++ /dev/null @@ -1,238 +0,0 @@ -=pod - -=head1 NAME - -bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, -bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, -bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, -bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, -bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, -bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, -bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low, sqr -- BIGNUM library internal functions - -=head1 SYNOPSIS - - #include - - BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); - BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, - BN_ULONG w); - void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); - BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); - BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - - void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); - void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); - - int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); - - void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, - int nb); - void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); - void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, - int dna,int dnb,BN_ULONG *tmp); - void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n, int tna,int tnb, BN_ULONG *tmp); - void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n2, BN_ULONG *tmp); - void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, - int n2, BN_ULONG *tmp); - - void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); - void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); - - void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); - - BIGNUM *bn_expand(BIGNUM *a, int bits); - BIGNUM *bn_wexpand(BIGNUM *a, int n); - BIGNUM *bn_expand2(BIGNUM *a, int n); - void bn_fix_top(BIGNUM *a); - - void bn_check_top(BIGNUM *a); - void bn_print(BIGNUM *a); - void bn_dump(BN_ULONG *d, int n); - void bn_set_max(BIGNUM *a); - void bn_set_high(BIGNUM *r, BIGNUM *a, int n); - void bn_set_low(BIGNUM *r, BIGNUM *a, int n); - -=head1 DESCRIPTION - -This page documents the internal functions used by the OpenSSL -B implementation. They are described here to facilitate -debugging and extending the library. They are I to be used by -applications. - -=head2 The BIGNUM structure - - typedef struct bignum_st BIGNUM; - - struct bignum_st - { - BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ - int top; /* Index of last used d +1. */ - /* The next are internal book keeping for bn_expand. */ - int dmax; /* Size of the d array. */ - int neg; /* one if the number is negative */ - int flags; - }; - - -The integer value is stored in B, a malloc()ed array of words (B), -least significant word first. A B can be either 16, 32 or 64 bits -in size, depending on the 'number of bits' (B) specified in -C. - -B is the size of the B array that has been allocated. B -is the number of words being used, so for a value of 4, bn.d[0]=4 and -bn.top=1. B is 1 if the number is negative. When a B is -B<0>, the B field can be B and B == B<0>. - -B is a bit field of flags which are defined in C. The -flags begin with B. The macros BN_set_flags(b,n) and -BN_get_flags(b,n) exist to enable or fetch flag(s) B from B -structure B. - -Various routines in this library require the use of temporary -B variables during their execution. Since dynamic memory -allocation to create Bs is rather expensive when used in -conjunction with repeated subroutine calls, the B structure is -used. This structure contains B Bs, see -L. - -=head2 Low-level arithmetic operations - -These functions are implemented in C and for several platforms in -assembly language: - -bn_mul_words(B, B, B, B) operates on the B word -arrays B and B. It computes B * B, places the result -in B, and returns the high word (carry). - -bn_mul_add_words(B, B, B, B) operates on the B -word arrays B and B. It computes B * B + B, places -the result in B, and returns the high word (carry). - -bn_sqr_words(B, B, B) operates on the B word array -B and the 2*B word array B. It computes B * B -word-wise, and places the low and high bytes of the result in B. - -bn_div_words(B, B, B) divides the two word number (B,B) -by B and returns the result. - -bn_add_words(B, B, B, B) operates on the B word -arrays B, B and B. It computes B + B, places the -result in B, and returns the high word (carry). - -bn_sub_words(B, B, B, B) operates on the B word -arrays B, B and B. It computes B - B, places the -result in B, and returns the carry (1 if B E B, 0 -otherwise). - -bn_mul_comba4(B, B, B) operates on the 4 word arrays B and -B and the 8 word array B. It computes B*B and places the -result in B. - -bn_mul_comba8(B, B, B) operates on the 8 word arrays B and -B and the 16 word array B. It computes B*B and places the -result in B. - -bn_sqr_comba4(B, B, B) operates on the 4 word arrays B and -B and the 8 word array B. - -bn_sqr_comba8(B, B, B) operates on the 8 word arrays B and -B and the 16 word array B. - -The following functions are implemented in C: - -bn_cmp_words(B, B, B) operates on the B word arrays B -and B. It returns 1, 0 and -1 if B is greater than, equal and -less than B. - -bn_mul_normal(B, B, B, B, B) operates on the B -word array B, the B word array B and the B+B word -array B. It computes B*B and places the result in B. - -bn_mul_low_normal(B, B, B, B) operates on the B word -arrays B, B and B. It computes the B low words of -B*B and places the result in B. - -bn_mul_recursive(B, B, B, B, B, B, B) operates -on the word arrays B and B of length B+B and B+B -(B and B are currently allowed to be 0 or negative) and the 2*B -word arrays B and B. B must be a power of 2. It computes -B*B and places the result in B. - -bn_mul_part_recursive(B, B, B, B, B, B, B) -operates on the word arrays B and B of length B+B and -B+B and the 4*B word arrays B and B. - -bn_mul_low_recursive(B, B, B, B, B) operates on the -B word arrays B and B and the B/2 word arrays B -and B. - -bn_mul_high(B, B, B, B, B, B) operates on the -B word arrays B, B, B and B (?) and the 3*B word -array B. - -BN_mul() calls bn_mul_normal(), or an optimized implementation if the -factors have the same size: bn_mul_comba8() is used if they are 8 -words long, bn_mul_recursive() if they are larger than -B and the size is an exact multiple of the word -size, and bn_mul_part_recursive() for others that are larger than -B. - -bn_sqr_normal(B, B, B, B) operates on the B word array -B and the 2*B word arrays B and B. - -The implementations use the following macros which, depending on the -architecture, may use "long long" C operations or inline assembler. -They are defined in C. - -mul(B, B, B, B) computes B*B+B and places the -low word of the result in B and the high word in B. - -mul_add(B, B, B, B) computes B*B+B+B and -places the low word of the result in B and the high word in B. - -sqr(B, B, B) computes B*B and places the low word -of the result in B and the high word in B. - -=head2 Size changes - -bn_expand() ensures that B has enough space for a B bit -number. bn_wexpand() ensures that B has enough space for an -B word number. If the number has to be expanded, both macros -call bn_expand2(), which allocates a new B array and copies the -data. They return B on error, B otherwise. - -The bn_fix_top() macro reduces Btop> to point to the most -significant non-zero word plus one when B has shrunk. - -=head2 Debugging - -bn_check_top() verifies that C<((a)-Etop E= 0 && (a)-Etop -E= (a)-Edmax)>. A violation will cause the program to abort. - -bn_print() prints B to stderr. bn_dump() prints B words at B -(in reverse order, i.e. most significant word first) to stderr. - -bn_set_max() makes B a static number with a B of its current size. -This is used by bn_set_low() and bn_set_high() to make B a read-only -B that contains the B low or high words of B. - -If B is not defined, bn_check_top(), bn_print(), bn_dump() -and bn_set_max() are defined as empty macros. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod b/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod deleted file mode 100644 index fc7335c7a1..0000000000 --- a/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_bio, -i2d_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp -- PKCS#8 format private key functions - -=head1 SYNOPSIS - - #include - - EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); - EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - -=head1 DESCRIPTION - -The PKCS#8 functions encode and decode private keys in PKCS#8 format using both -PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. - -Other than the use of DER as opposed to PEM these functions are identical to the -corresponding B function as described in the L manual page. - -=head1 NOTES - -Before using these functions -L should be called -to initialize the internal algorithm lookup tables otherwise errors about -unknown algorithms will occur if an attempt is made to decrypt a private key. - -These functions are currently the only way to store encrypted private keys -using DER format. - -Currently all the functions use BIOs or FILE pointers, there are no functions -which work directly on memory: this can be readily worked around by converting -the buffers to memory BIOs, see L for details. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ecdsa.pod b/src/lib/libssl/src/doc/crypto/ecdsa.pod deleted file mode 100644 index 9e9608155a..0000000000 --- a/src/lib/libssl/src/doc/crypto/ecdsa.pod +++ /dev/null @@ -1,205 +0,0 @@ -=pod - -=head1 NAME - -ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, -ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, -ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify, -ECDSA_OpenSSL, ECDSA_get_default_method, ECDSA_get_ex_data, -ECDSA_get_ex_new_index, ECDSA_set_default_method, ECDSA_set_ex_data, -ECDSA_set_method - Elliptic Curve Digital Signature Algorithm - -=head1 SYNOPSIS - - #include - - ECDSA_SIG* ECDSA_SIG_new(void); - void ECDSA_SIG_free(ECDSA_SIG *sig); - int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); - ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, - long len); - - ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, - EC_KEY *eckey); - ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, - const BIGNUM *kinv, const BIGNUM *rp, - EC_KEY *eckey); - int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, - const ECDSA_SIG *sig, EC_KEY* eckey); - int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, - BIGNUM **kinv, BIGNUM **rp); - int ECDSA_sign(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, EC_KEY *eckey); - int ECDSA_sign_ex(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, const BIGNUM *kinv, - const BIGNUM *rp, EC_KEY *eckey); - int ECDSA_verify(int type, const unsigned char *dgst, - int dgstlen, const unsigned char *sig, - int siglen, EC_KEY *eckey); - int ECDSA_size(const EC_KEY *eckey); - - const ECDSA_METHOD* ECDSA_OpenSSL(void); - void ECDSA_set_default_method(const ECDSA_METHOD *meth); - const ECDSA_METHOD* ECDSA_get_default_method(void); - int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - -=head1 DESCRIPTION - -The B structure consists of two BIGNUMs for the -r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). - - struct - { - BIGNUM *r; - BIGNUM *s; - } ECDSA_SIG; - -ECDSA_SIG_new() allocates a new B structure (note: this -function also allocates the BIGNUMs) and initialize it. - -ECDSA_SIG_free() frees the B structure B. - -i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature -B and writes the encoded signature to B<*pp> (note: if B -is NULL B returns the expected length in bytes of -the DER encoded signature). B returns the length -of the DER encoded signature (or 0 on error). - -d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns -the decoded signature in a newly allocated B structure. -B<*sig> points to the buffer containing the DER encoded signature -of size B. - -ECDSA_size() returns the maximum length of a DER encoded -ECDSA signature created with the private EC key B. - -ECDSA_sign_setup() may be used to precompute parts of the -signing operation. B is the private EC key and B -is a pointer to B structure (or NULL). The precomputed -values or returned in B and B and can be used in a -later call to B or B. - -ECDSA_sign() is wrapper function for ECDSA_sign_ex with B -and B set to NULL. - -ECDSA_sign_ex() computes a digital signature of the B bytes -hash value B using the private EC key B and the optional -pre-computed values B and B. The DER encoded signatures is -stored in B and it's length is returned in B. Note: B -must point to B bytes of memory. The parameter B -is ignored. - -ECDSA_verify() verifies that the signature in B of size -B is a valid ECDSA signature of the hash value -B of size B using the public key B. -The parameter B is ignored. - -ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B -and B set to NULL. - -ECDSA_do_sign_ex() computes a digital signature of the B -bytes hash value B using the private key B and the -optional pre-computed values B and B. The signature is -returned in a newly allocated B structure (or NULL on error). - -ECDSA_do_verify() verifies that the signature B is a valid -ECDSA signature of the hash value B of size B -using the public key B. - -=head1 RETURN VALUES - -ECDSA_size() returns the maximum length signature or 0 on error. - -ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 -on error. - -ECDSA_verify() and ECDSA_do_verify() return 1 for a valid -signature, 0 for an invalid signature and -1 on error. -The error codes can be obtained by L. - -=head1 EXAMPLES - -Creating a ECDSA signature of given SHA-1 hash value using the -named curve secp192k1. - -First step: create a EC_KEY object (note: this part is B ECDSA -specific) - - int ret; - ECDSA_SIG *sig; - EC_KEY *eckey; - - eckey = EC_KEY_new_by_curve_name(NID_secp192k1); - if (eckey == NULL) { - /* error */ - } - if (!EC_KEY_generate_key(eckey)) { - /* error */ - } - -Second step: compute the ECDSA signature of a SHA-1 hash value -using B - - sig = ECDSA_do_sign(digest, 20, eckey); - if (sig == NULL) { - /* error */ - } - -or using B - - unsigned char *buffer, *pp; - int buf_len; - - buf_len = ECDSA_size(eckey); - buffer = malloc(buf_len); - pp = buffer; - if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) { - /* error */ - } - -Third step: verify the created ECDSA signature using B - - ret = ECDSA_do_verify(digest, 20, sig, eckey); - -or using B - - ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); - -and finally evaluate the return value: - - if (ret == -1) { - /* error */ - } else if (ret == 0) { - /* incorrect signature */ - } else { - /* ret == 1 */ - /* signature ok */ - } - -=head1 CONFORMING TO - -ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 -(Digital Signature Standard, DSS) - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -The ecdsa implementation was first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/src/lib/libssl/src/doc/crypto/lhash.pod b/src/lib/libssl/src/doc/crypto/lhash.pod deleted file mode 100644 index a9c44dd9ef..0000000000 --- a/src/lib/libssl/src/doc/crypto/lhash.pod +++ /dev/null @@ -1,303 +0,0 @@ -=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 - - DECLARE_LHASH_OF(); - - LHASH *lh__new(); - void lh__free(LHASH_OF( *table); - - *lh__insert(LHASH_OF( *table, *data); - *lh__delete(LHASH_OF( *table, *data); - *lh_retrieve(LHASH_OF *table, *data); - - void lh__doall(LHASH_OF( *table, LHASH_DOALL_FN_TYPE func); - void lh__doall_arg(LHASH_OF( *table, LHASH_DOALL_ARG_FN_TYPE func, - , *arg); - - int lh__error(LHASH_OF( *table); - - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); - -=head1 DESCRIPTION - -This library implements type-checked 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 to store -arbitrary data entries, and provides the 'hash' and 'compare' -callbacks to be used in organising the table's entries. The B -callback takes a pointer to a table entry as its argument and returns -an unsigned long hash value for 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. The B callback -takes two arguments (pointers to two hash table entries), and returns -0 if their keys are equal, non-zero otherwise. If your hash table -will contain items of some particular type and the B and -B callbacks hash/compare these types, then the -B and B macros can be -used to create callback wrappers of the prototypes required by -lh__new(). These provide per-variable casts before calling the -type-specific callbacks written by the application author. These -macros, as well as those used for the "doall" callbacks, are defined -as; - - #define DECLARE_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *arg) { \ - const o_type *a = arg; \ - return name##_hash(a); } - #define LHASH_HASH_FN(name) name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - const o_type *a = arg1; \ - const o_type *b = arg2; \ - return name##_cmp(a,b); } - #define LHASH_COMP_FN(name) name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *); - #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *arg) { \ - o_type *a = arg; \ - name##_doall(a); } - #define LHASH_DOALL_FN(name) name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *, void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ - o_type *a = arg1; \ - a_type *b = arg2; \ - name##_doall_arg(a, b); } - #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG - - An example of a hash table storing (pointers to) structures of type 'STUFF' - could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int stuff_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); - static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ - } - -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 (see below). - -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 its parameter. For lh__doall() -and lh__doall_arg(), function pointer casting should be avoided -in the callbacks (see B) - instead use the declare/implement -macros to create type-checked wrappers that cast variables prior to -calling your type-specific callbacks. An example of this is -illustrated here where the callback is used to cleanup resources for -items in the hash table prior to the hashtable itself being -deallocated: - - /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup_doall(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); - /* Then the hash table itself can be deallocated */ - lh_STUFF_free(hashtable); - -When doing this, be careful if you delete entries from the hash table -in your callbacks: the table may decrease in size, moving the item -that you are currently on down lower in the hash table - this could -cause some entries to be skipped during the iteration. The second -best solution to this problem is to set hash-Edown_load=0 before -you start (which will stop the hash table ever decreasing in size). -The best solution is probably to avoid deleting items from the hash -table inside a "doall" callback! - -lh__doall_arg() is the same as lh__doall() except that -B will be called with B as the second argument and B -should be of type B (a callback prototype -that is passed both the table entry and an extra argument). As with -lh_doall(), you can instead choose to declare your callback with a -prototype matching the types you are dealing with and use the -declare/implement macros to create compatible wrappers that cast -variables before calling your type-specific callbacks. An example of -this is demonstrated here (printing all hash table entries to a BIO -that is provided by the caller): - - /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) - /* ... then later in the code ... */ - /* Print out the entire hashtable to a particular BIO */ - lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, - logging_bio); - -lh__error() can be used to determine if an error occurred 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 NOTE - -The various LHASH macros and callback types exist to make it possible -to write type-checked code without resorting to function-prototype -casting - an evil that makes application code much harder to -audit/verify and also opens the window of opportunity for stack -corruption and other hard-to-find bugs. It also, apparently, violates -ANSI-C. - -The LHASH code regards table entries as constant data. As such, it -internally represents lh_insert()'d items with a "const void *" -pointer type. This is why callbacks such as those used by lh_doall() -and lh_doall_arg() declare their prototypes with "const", even for the -parameters that pass back the table items' data pointers - for -consistency, user-provided data is "const" at all times as far as the -LHASH code is concerned. However, as callers are themselves providing -these pointers, they can choose whether they too should be treating -all such parameters as constant. - -As an example, a hash table may be maintained by code that, for -reasons of encapsulation, has only "const" access to the data being -indexed in the hash table (ie. it is returned as "const" from -elsewhere in their code) - in this case the LHASH prototypes are -appropriate as-is. Conversely, if the caller is responsible for the -life-time of the data in question, then they may well wish to make -modifications to table item passed back in the lh_doall() or -lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If -so, the caller can either cast the "const" away (if they're providing -the raw callbacks themselves) or use the macros to declare/implement -the wrapper functions without "const" types. - -Callers that only have "const" access to data they're indexing in a -table, yet declare callbacks without constant types (or cast the -"const" away themselves), are therefore creating their own risks/bugs -without being encouraged to do so by the API. On a related note, -those auditing code should pay special attention to any instances of -DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types -without any "const" qualifiers. - -=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 OPENSSL_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 your 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. - -In OpenSSL 0.9.7, all lhash functions that were passed function pointers -were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, -LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE -became available. - -In OpenSSL 1.0.0, the lhash interface was revamped for even better -type checking. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ui.pod b/src/lib/libssl/src/doc/crypto/ui.pod deleted file mode 100644 index 6df68d604a..0000000000 --- a/src/lib/libssl/src/doc/crypto/ui.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, -UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, -UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, -UI_add_error_string, UI_dup_error_string, UI_construct_prompt, -UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, -UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface - -=head1 SYNOPSIS - - #include - - typedef struct ui_st UI; - typedef struct ui_method_st UI_METHOD; - - UI *UI_new(void); - UI *UI_new_method(const UI_METHOD *method); - void UI_free(UI *ui); - - int UI_add_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); - int UI_dup_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); - int UI_add_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); - int UI_dup_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); - int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); - int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); - int UI_add_info_string(UI *ui, const char *text); - int UI_dup_info_string(UI *ui, const char *text); - int UI_add_error_string(UI *ui, const char *text); - int UI_dup_error_string(UI *ui, const char *text); - - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - - char *UI_construct_prompt(UI *ui_method, - const char *object_desc, const char *object_name); - - void *UI_add_user_data(UI *ui, void *user_data); - void *UI_get0_user_data(UI *ui); - - const char *UI_get0_result(UI *ui, int i); - - int UI_process(UI *ui); - - int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 - - void UI_set_default_method(const UI_METHOD *meth); - const UI_METHOD *UI_get_default_method(void); - const UI_METHOD *UI_get_method(UI *ui); - const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); - - UI_METHOD *UI_OpenSSL(void); - -=head1 DESCRIPTION - -UI stands for User Interface, and is general purpose set of routines to -prompt the user for text-based information. Through user-written methods -(see L), prompting can be done in any way -imaginable, be it plain text prompting, through dialog boxes or from a -cell phone. - -All the functions work through a context of the type UI. This context -contains all the information needed to prompt correctly as well as a -reference to a UI_METHOD, which is an ordered vector of functions that -carry out the actual prompting. - -The first thing to do is to create a UI with UI_new() or UI_new_method(), -then add information to it with the UI_add or UI_dup functions. Also, -user-defined random data can be passed down to the underlying method -through calls to UI_add_user_data. The default UI method doesn't care -about these data, but other methods might. Finally, use UI_process() -to actually perform the prompting and UI_get0_result() to find the result -to the prompt. - -A UI can contain more than one prompt, which are performed in the given -sequence. Each prompt gets an index number which is returned by the -UI_add and UI_dup functions, and has to be used to get the corresponding -result with UI_get0_result(). - -The functions are as follows: - -UI_new() creates a new UI using the default UI method. When done with -this UI, it should be freed using UI_free(). - -UI_new_method() creates a new UI using the given UI method. When done with -this UI, it should be freed using UI_free(). - -UI_OpenSSL() returns the built-in UI method (note: not the default one, -since the default can be changed. See further on). This method is the -most machine/OS dependent part of OpenSSL and normally generates the -most problems when porting. - -UI_free() removes a UI from memory, along with all other pieces of memory -that's connected to it, like duplicated input strings, results and others. - -UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, -as well as flags and a result buffer and the desired minimum and maximum -sizes of the result. The given information is used to prompt for -information, for example a password, and to verify a password (i.e. having -the user enter it twice and check that the same string was entered twice). -UI_add_verify_string() takes and extra argument that should be a pointer -to the result buffer of the input string that it's supposed to verify, or -verification will fail. - -UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered -in a boolean way, with a single character for yes and a different character -for no. A set of characters that can be used to cancel the prompt is given -as well. The prompt itself is really divided in two, one part being the -descriptive text (given through the I argument) and one describing -the possible answers (given through the I argument). - -UI_add_info_string() and UI_add_error_string() add strings that are shown at -the same time as the prompt for extra information or to show an error string. -The difference between the two is only conceptual. With the builtin method, -there's no technical difference between them. Other methods may make a -difference between them, however. - -The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for -UI_add_input_string() and will have the users response be echoed (when -prompting for a password, this flag should obviously not be used, and -UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some -sort will be used (completely depending on the application and the UI -method). - -UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), -UI_dup_info_string() and UI_dup_error_string() are basically the same -as their UI_add counterparts, except that they make their own copies -of all strings. - -UI_construct_prompt() is a helper function that can be used to create -a prompt from two pieces of information: an description and a name. -The default constructor (if there is none provided by the method used) -creates a string "Enter I for I:". With the -description "pass phrase" and the file name "foo.key", that becomes -"Enter pass phrase for foo.key:". Other methods may create whatever -string and may include encodings that will be processed by the other -method functions. - -UI_add_user_data() adds a piece of memory for the method to use at any -time. The builtin UI method doesn't care about this info. Note that several -calls to this function doesn't add data, it replaces the previous blob -with the one given as argument. - -UI_get0_user_data() retrieves the data that has last been given to the -UI with UI_add_user_data(). - -UI_get0_result() returns a pointer to the result buffer associated with -the information indexed by I. - -UI_process() goes through the information given so far, does all the printing -and prompting and returns. - -UI_ctrl() adds extra control for the application author. For now, it -understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() -print the OpenSSL error stack as part of processing the UI, and -UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can -be used again or not. - -UI_set_default_method() changes the default UI method to the one given. - -UI_get_default_method() returns a pointer to the current default UI method. - -UI_get_method() returns the UI method associated with a given UI. - -UI_set_method() changes the UI method associated with a given UI. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -The UI section was first introduced in OpenSSL 0.9.7. - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ui_compat.pod b/src/lib/libssl/src/doc/crypto/ui_compat.pod deleted file mode 100644 index 4ef5465539..0000000000 --- a/src/lib/libssl/src/doc/crypto/ui_compat.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - -Compatibility user interface functions - -=head1 SYNOPSIS - - #include - - int des_read_password(DES_cblock *key,const char *prompt,int verify); - int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, - const char *prompt,int verify); - - int des_read_pw_string(char *buf,int length,const char *prompt,int verify); - int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); - -=head1 DESCRIPTION - -The DES library contained a few routines to prompt for passwords. These -aren't necessarily dependent on DES, and have therefore become part of the -UI compatibility library. - -des_read_pw() writes the string specified by I to standard output -turns echo off and reads an input string from the terminal. The string is -returned in I, which must have space for at least I bytes. -If I is set, the user is asked for the password twice and unless -the two copies match, an error is returned. The second password is stored -in I, which must therefore also be at least I bytes. A return -code of -1 indicates a system error, 1 failure due to use interaction, and -0 is success. All other functions described here use des_read_pw() to do -the work. - -des_read_pw_string() is a variant of des_read_pw() that provides a buffer -for you if I is set. - -des_read_password() calls des_read_pw() and converts the password to a -DES key by calling DES_string_to_key(); des_read_2password() operates in -the same way as des_read_password() except that it generates two keys -by using the DES_string_to_2key() function. - -=head1 NOTES - -des_read_pw_string() is available in the MIT Kerberos library as well, and -is also available under the name EVP_read_pw_string(). - -=head1 SEE ALSO - -L, L - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut -- cgit v1.2.3-55-g6feb