diff options
Diffstat (limited to 'lib/libcrypto/doc')
| -rw-r--r-- | lib/libcrypto/doc/RC4.pod | 62 | ||||
| -rw-r--r-- | lib/libcrypto/doc/RIPEMD160.pod | 66 | ||||
| -rw-r--r-- | lib/libcrypto/doc/SHA1.pod | 71 | ||||
| -rw-r--r-- | lib/libcrypto/doc/bn.pod | 181 | ||||
| -rw-r--r-- | lib/libcrypto/doc/d2i_DHparams.pod | 26 | ||||
| -rw-r--r-- | lib/libcrypto/doc/d2i_DSAPublicKey.pod | 79 | ||||
| -rw-r--r-- | lib/libcrypto/doc/d2i_ECPKParameters.pod | 84 | ||||
| -rw-r--r-- | lib/libcrypto/doc/dh.pod | 79 | ||||
| -rw-r--r-- | lib/libcrypto/doc/dsa.pod | 114 | ||||
| -rw-r--r-- | lib/libcrypto/doc/ec.pod | 201 | ||||
| -rw-r--r-- | lib/libcrypto/doc/engine.pod | 599 | ||||
| -rw-r--r-- | lib/libcrypto/doc/lh_stats.pod | 60 |
12 files changed, 0 insertions, 1622 deletions
diff --git a/lib/libcrypto/doc/RC4.pod b/lib/libcrypto/doc/RC4.pod deleted file mode 100644 index b6d3a4342ca..00000000000 --- a/lib/libcrypto/doc/RC4.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -RC4_set_key, RC4 - RC4 encryption - -=head1 SYNOPSIS - - #include <openssl/rc4.h> - - void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); - - void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, - unsigned char *outdata); - -=head1 DESCRIPTION - -This library implements the Alleged RC4 cipher, which is described for -example in I<Applied Cryptography>. It is believed to be compatible -with RC4[TM], a proprietary cipher of RSA Security Inc. - -RC4 is a stream cipher with variable key length. Typically, 128 bit -(16 byte) keys are used for strong encryption, but shorter insecure -key sizes have been widely used due to export restrictions. - -RC4 consists of a key setup phase and the actual encryption or -decryption phase. - -RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long -key at B<data>. - -RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using -B<key> and places the result at B<outdata>. Repeated RC4() calls with -the same B<key> yield a continuous key stream. - -Since RC4 is a stream cipher (the input is XORed with a pseudo-random -key stream to produce the output), decryption uses the same function -calls as encryption. - -Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> -etc. instead of calling the RC4 functions directly. - -=head1 RETURN VALUES - -RC4_set_key() and RC4() do not return values. - -=head1 NOTE - -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. - -=head1 SEE ALSO - -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> - -=head1 HISTORY - -RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/lib/libcrypto/doc/RIPEMD160.pod b/lib/libcrypto/doc/RIPEMD160.pod deleted file mode 100644 index f66fb02ed2b..00000000000 --- a/lib/libcrypto/doc/RIPEMD160.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - -RIPEMD-160 hash function - -=head1 SYNOPSIS - - #include <openssl/ripemd.h> - - unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, - unsigned char *md); - - int RIPEMD160_Init(RIPEMD160_CTX *c); - int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, - unsigned long len); - int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); - -=head1 DESCRIPTION - -RIPEMD-160 is a cryptographic hash function with a -160 bit output. - -RIPEMD160() computes the RIPEMD-160 message digest of the B<n> -bytes at B<d> and places it in B<md> (which must have space for -RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> 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: - -RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. - -RIPEMD160_Update() can be called repeatedly with chunks of the message to -be hashed (B<len> bytes at B<data>). - -RIPEMD160_Final() places the message digest in B<md>, which must have -space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases -the B<RIPEMD160_CTX>. - -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the -hash functions directly. - -=head1 RETURN VALUES - -RIPEMD160() returns a pointer to the hash value. - -RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for -success, 0 otherwise. - -=head1 CONFORMING TO - -ISO/IEC 10118-3 (draft) (??) - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. - -=cut diff --git a/lib/libcrypto/doc/SHA1.pod b/lib/libcrypto/doc/SHA1.pod deleted file mode 100644 index 9fffdf59e7b..00000000000 --- a/lib/libcrypto/doc/SHA1.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm - -=head1 SYNOPSIS - - #include <openssl/sha.h> - - unsigned char *SHA1(const unsigned char *d, unsigned long n, - unsigned char *md); - - int SHA1_Init(SHA_CTX *c); - int SHA1_Update(SHA_CTX *c, const void *data, - unsigned long len); - int 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. - -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. - -The following functions may be used if the message is not completely -stored in memory: - -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>. - -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> -etc. instead of calling the hash functions directly. - -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() return 1 for success, 0 otherwise. - -=head1 CONFORMING TO - -SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash -Standard), -SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash -Standard), -ANSI X9.30 - -=head1 SEE ALSO - -L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. - -=cut diff --git a/lib/libcrypto/doc/bn.pod b/lib/libcrypto/doc/bn.pod deleted file mode 100644 index b3ad63320a1..00000000000 --- a/lib/libcrypto/doc/bn.pod +++ /dev/null @@ -1,181 +0,0 @@ -=pod - -=head1 NAME - -bn - multiprecision integer arithmetics - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - void BN_free(BIGNUM *a); - void BN_init(BIGNUM *); - void BN_clear(BIGNUM *a); - void BN_clear_free(BIGNUM *a); - - BN_CTX *BN_CTX_new(void); - void BN_CTX_init(BN_CTX *c); - void BN_CTX_free(BN_CTX *c); - - BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); - BIGNUM *BN_dup(const BIGNUM *a); - - BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); - - int BN_num_bytes(const BIGNUM *a); - int BN_num_bits(const BIGNUM *a); - int BN_num_bits_word(BN_ULONG w); - - void BN_set_negative(BIGNUM *a, int n); - int BN_is_negative(const BIGNUM *a); - - int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, - BN_CTX *ctx); - int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - int BN_add_word(BIGNUM *a, BN_ULONG w); - int BN_sub_word(BIGNUM *a, BN_ULONG w); - int BN_mul_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); - - int BN_cmp(BIGNUM *a, BIGNUM *b); - int BN_ucmp(BIGNUM *a, BIGNUM *b); - int BN_is_zero(BIGNUM *a); - int BN_is_one(BIGNUM *a); - int BN_is_word(BIGNUM *a, BN_ULONG w); - int BN_is_odd(BIGNUM *a); - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - const BIGNUM *BN_value_one(void); - int BN_set_word(BIGNUM *a, unsigned long w); - 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); - int BN_rand_range(BIGNUM *rnd, BIGNUM *range); - int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); - - BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, - BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); - int BN_is_prime(const BIGNUM *p, int nchecks, - void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); - - int BN_set_bit(BIGNUM *a, int n); - int BN_clear_bit(BIGNUM *a, int n); - int BN_is_bit_set(const BIGNUM *a, int n); - int BN_mask_bits(BIGNUM *a, int n); - int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); - int BN_lshift1(BIGNUM *r, BIGNUM *a); - int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - int BN_rshift1(BIGNUM *r, BIGNUM *a); - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); - char *BN_bn2hex(const BIGNUM *a); - char *BN_bn2dec(const BIGNUM *a); - int BN_hex2bn(BIGNUM **a, const char *str); - int BN_dec2bn(BIGNUM **a, const char *str); - int BN_print(BIO *fp, const BIGNUM *a); - int BN_print_fp(FILE *fp, const BIGNUM *a); - int BN_bn2mpi(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - - BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_init(BN_RECP_CTX *recp); - void BN_RECP_CTX_free(BN_RECP_CTX *recp); - int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - - BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); - void BN_MONT_CTX_free(BN_MONT_CTX *mont); - int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); - BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); - int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_MONT_CTX *mont, BN_CTX *ctx); - int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - - BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, - BIGNUM *mod); - void BN_BLINDING_free(BN_BLINDING *b); - int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); - int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); - int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, - BN_CTX *ctx); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); - void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); - BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); - -=head1 DESCRIPTION - -This library performs arithmetic operations on integers of arbitrary -size. It was written for use in public key cryptography, such as RSA -and Diffie-Hellman. - -It uses dynamic memory allocation for storing its data structures. -That means that there is no limit on the size of the numbers -manipulated by these functions, but return values must always be -checked in case a memory allocation error has occurred. - -The basic object in this library is a B<BIGNUM>. It is used to hold a -single large integer. This type should be considered opaque and fields -should not be modified or accessed directly. - -The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; -L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. -Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> -describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of -random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime -numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion -of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. - -=head1 SEE ALSO - -L<bn_dump(3)|bn_dump(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<BN_new(3)|BN_new(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)>, L<BN_copy(3)|BN_copy(3)>, -L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, -L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, -L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, -L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, -L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, -L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, -L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> - -=cut diff --git a/lib/libcrypto/doc/d2i_DHparams.pod b/lib/libcrypto/doc/d2i_DHparams.pod deleted file mode 100644 index 9f1aac9137a..00000000000 --- a/lib/libcrypto/doc/d2i_DHparams.pod +++ /dev/null @@ -1,26 +0,0 @@ -=pod - -=head1 NAME - -d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - DH *d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(DH *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode PKCS#3 DH parameters using the -DHparameter structure described in PKCS#3. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=cut diff --git a/lib/libcrypto/doc/d2i_DSAPublicKey.pod b/lib/libcrypto/doc/d2i_DSAPublicKey.pod deleted file mode 100644 index 10c49e3ad28..00000000000 --- a/lib/libcrypto/doc/d2i_DSAPublicKey.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, -d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding -and parsing functions. - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/x509.h> - - DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); - - int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAparams(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); - - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key -components structure. - -d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key -components. - -d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using -a B<Dss-Parms> structure as defined in RFC2459. - -d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a -B<Dss-Sig-Value> structure as defined in RFC2459. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<DSA> structure passed to the private key encoding functions should have -all the private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> -functions when encoding public keys because they use a standard format. - -The B<DSAPublicKey> functions use an non standard format the actual data encoded -depends on the value of the B<write_params> field of the B<a> key parameter. -If B<write_params> is zero then only the B<pub_key> field is encoded as an -B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the -B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. - -The B<DSAPrivateKey> functions also use a non standard structure consisting -consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and -B<priv_key> fields respectively. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=cut diff --git a/lib/libcrypto/doc/d2i_ECPKParameters.pod b/lib/libcrypto/doc/d2i_ECPKParameters.pod deleted file mode 100644 index 704b4ab3528..00000000000 --- a/lib/libcrypto/doc/d2i_ECPKParameters.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities - -=head1 SYNOPSIS - - #include <openssl/ec.h> - - EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - -=head1 DESCRIPTION - -The ECPKParameters encode and decode routines encode and parse the public parameters for an -B<EC_GROUP> structure, which represents a curve. - -d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<EC_GROUP> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<EC_GROUP> -structure and an attempt is made to reuse it. If the call is -successful B<*in> is incremented to the byte following the -parsed data. - -i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, and increments it to point after the data just written. -If the return value is negative an error occurred, otherwise it -returns the length of the encoded data. - -If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded -data written to it. In this case B<*out> is not incremented and it points to -the start of the data just written. - -d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts -to parse data from BIO B<bp>. - -d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>, -where further notes and examples are available. - -The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output -of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces. - -=head1 RETURN VALUES - -d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure -or B<NULL> if an error occurs. - -i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative -value if an error occurs. - -i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp -return 1 for success and 0 if an error occurs. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)> - -=cut diff --git a/lib/libcrypto/doc/dh.pod b/lib/libcrypto/doc/dh.pod deleted file mode 100644 index 5fb9890a770..00000000000 --- a/lib/libcrypto/doc/dh.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -dh - Diffie-Hellman key agreement - -=head1 SYNOPSIS - - #include <openssl/dh.h> - #include <openssl/engine.h> - - DH * DH_new(void); - void DH_free(DH *dh); - - int DH_size(const DH *dh); - - DH * DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - int DH_check(const DH *dh, int *codes); - - int DH_generate_key(DH *dh); - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - - void DH_set_default_method(const DH_METHOD *meth); - const DH_METHOD *DH_get_default_method(void); - int DH_set_method(DH *dh, const DH_METHOD *meth); - DH *DH_new_method(ENGINE *engine); - const 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(const DH *a, unsigned char **pp); - - int DHparams_print_fp(FILE *fp, const DH *x); - int DHparams_print(BIO *bp, const DH *x); - -=head1 DESCRIPTION - -These functions implement the Diffie-Hellman key agreement protocol. The -generation of shared DH parameters is described in -L<DH_generate_parameters(3)|DH_generate_parameters(3)>; -L<DH_generate_key(3)|DH_generate_key(3)> describes how to perform a key -agreement. - -The B<DH> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (shared) - BIGNUM *g; // generator of Z_p (shared) - BIGNUM *priv_key; // private DH value x - BIGNUM *pub_key; // public DH value g^x - // ... - }; - DH - -Note that DH keys may use non-standard B<DH_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DH -structure elements directly and instead use API functions to query or -modify keys. - -=head1 SEE ALSO - -L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, -L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/lib/libcrypto/doc/dsa.pod b/lib/libcrypto/doc/dsa.pod deleted file mode 100644 index da07d2b930c..00000000000 --- a/lib/libcrypto/doc/dsa.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -dsa - Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/engine.h> - - DSA * DSA_new(void); - void DSA_free(DSA *dsa); - - int DSA_size(const DSA *dsa); - - DSA * DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - - DH * DSA_dup_DH(const 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, - const unsigned char *sigbuf, int siglen, DSA *dsa); - - void DSA_set_default_method(const DSA_METHOD *meth); - const DSA_METHOD *DSA_get_default_method(void); - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - DSA *DSA_new_method(ENGINE *engine); - const 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(const 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(const DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - int i2d_DSAparams(const DSA *a,unsigned char **pp); - - int DSAparams_print(BIO *bp, const DSA *x); - int DSAparams_print_fp(FILE *fp, const DSA *x); - int DSA_print(BIO *bp, const DSA *x, int off); - int DSA_print_fp(FILE *bp, const 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)|DSA_generate_parameters(3)>; -L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to -generate a signature key. Signature generation and verification are -described in L<DSA_sign(3)|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. - -Note that DSA keys may use non-standard B<DSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, -L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, -L<DSA_new(3)|DSA_new(3)>, -L<DSA_size(3)|DSA_size(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_dup_DH(3)|DSA_dup_DH(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)>, -L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/lib/libcrypto/doc/ec.pod b/lib/libcrypto/doc/ec.pod deleted file mode 100644 index 891948e4f6e..00000000000 --- a/lib/libcrypto/doc/ec.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -ec - Elliptic Curve functions - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.h> - - const EC_METHOD *EC_GFp_simple_method(void); - const EC_METHOD *EC_GFp_mont_method(void); - const EC_METHOD *EC_GFp_nist_method(void); - const EC_METHOD *EC_GFp_nistp224_method(void); - const EC_METHOD *EC_GFp_nistp256_method(void); - const EC_METHOD *EC_GFp_nistp521_method(void); - - const EC_METHOD *EC_GF2m_simple_method(void); - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); - EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); - const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); - int EC_METHOD_get_field_type(const EC_METHOD *meth); - int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); - const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); - int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); - int EC_GROUP_get_curve_name(const EC_GROUP *group); - void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); - int EC_GROUP_get_asn1_flag(const EC_GROUP *group); - void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); - point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); - unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); - size_t EC_GROUP_get_seed_len(const EC_GROUP *); - size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); - int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_degree(const EC_GROUP *group); - int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_by_curve_name(int nid); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - - EC_POINT *EC_POINT_new(const EC_GROUP *group); - void EC_POINT_free(EC_POINT *point); - void EC_POINT_clear_free(EC_POINT *point); - int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); - EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); - const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); - int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); - int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); - int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); - int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); - int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); - int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); - int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); - int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); - int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); - int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); - int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_have_precompute_mult(const EC_GROUP *group); - - int EC_GROUP_get_basis_type(const EC_GROUP *); - int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); - EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - EC_KEY *EC_KEY_new(void); - int EC_KEY_get_flags(const EC_KEY *key); - void EC_KEY_set_flags(EC_KEY *key, int flags); - void EC_KEY_clear_flags(EC_KEY *key, int flags); - EC_KEY *EC_KEY_new_by_curve_name(int nid); - void EC_KEY_free(EC_KEY *key); - EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); - EC_KEY *EC_KEY_dup(const EC_KEY *src); - int EC_KEY_up_ref(EC_KEY *key); - const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); - int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); - const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); - int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); - const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); - int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); - void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void *EC_KEY_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); - int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); - int EC_KEY_generate_key(EC_KEY *key); - int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECParameters(EC_KEY *key, unsigned char **out); - - EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); - int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); - int ECParameters_print(BIO *bp, const EC_KEY *key); - int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); - int ECParameters_print_fp(FILE *fp, const EC_KEY *key); - int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); - EC_KEY *ECParameters_dup(EC_KEY *key); - #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \ - EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \ - EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) - - -=head1 DESCRIPTION - -This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. -In general an elliptic curve is one with an equation of the form: - -y^2 = x^3 + ax + b - -An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an -B<EC_POINT> structure. An B<EC_KEY> is used to hold a private/public key pair, where a private key is simply a BIGNUM and a -public key is a point on a curve (represented by an B<EC_POINT>). - -The library contains a number of alternative implementations of the different functions. Each implementation is optimised -for different scenarios. No matter which implementation is being used, the interface remains the same. The library -handles calling the correct implementation when an interface function is invoked. An implementation is represented by -an B<EC_METHOD> structure. - -The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>. Functions for -manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>. - -Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>, -whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>. - -For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>. - -For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - - -=cut diff --git a/lib/libcrypto/doc/engine.pod b/lib/libcrypto/doc/engine.pod deleted file mode 100644 index 31035af398a..00000000000 --- a/lib/libcrypto/doc/engine.pod +++ /dev/null @@ -1,599 +0,0 @@ -=pod - -=head1 NAME - -ENGINE_add, ENGINE_by_id, ENGINE_finish, ENGINE_get_first, -ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, -ENGINE_init, ENGINE_load_builtin_engines, ENGINE_remove -- ENGINE cryptographic module support - -=head1 SYNOPSIS - - #include <openssl/engine.h> - - ENGINE *ENGINE_get_first(void); - ENGINE *ENGINE_get_last(void); - ENGINE *ENGINE_get_next(ENGINE *e); - ENGINE *ENGINE_get_prev(ENGINE *e); - - int ENGINE_add(ENGINE *e); - int ENGINE_remove(ENGINE *e); - - ENGINE *ENGINE_by_id(const char *id); - - int ENGINE_init(ENGINE *e); - int ENGINE_finish(ENGINE *e); - - void ENGINE_load_openssl(void); - void ENGINE_load_dynamic(void); - void ENGINE_load_cryptodev(void); - void ENGINE_load_builtin_engines(void); - - void ENGINE_cleanup(void); - - ENGINE *ENGINE_get_default_RSA(void); - ENGINE *ENGINE_get_default_DSA(void); - ENGINE *ENGINE_get_default_ECDH(void); - ENGINE *ENGINE_get_default_ECDSA(void); - ENGINE *ENGINE_get_default_DH(void); - ENGINE *ENGINE_get_default_RAND(void); - ENGINE *ENGINE_get_cipher_engine(int nid); - ENGINE *ENGINE_get_digest_engine(int nid); - - int ENGINE_set_default_RSA(ENGINE *e); - int ENGINE_set_default_DSA(ENGINE *e); - int ENGINE_set_default_ECDH(ENGINE *e); - int ENGINE_set_default_ECDSA(ENGINE *e); - int ENGINE_set_default_DH(ENGINE *e); - int ENGINE_set_default_RAND(ENGINE *e); - int ENGINE_set_default_ciphers(ENGINE *e); - int ENGINE_set_default_digests(ENGINE *e); - int ENGINE_set_default_string(ENGINE *e, const char *list); - - int ENGINE_set_default(ENGINE *e, unsigned int flags); - - unsigned int ENGINE_get_table_flags(void); - void ENGINE_set_table_flags(unsigned int flags); - - int ENGINE_register_RSA(ENGINE *e); - void ENGINE_unregister_RSA(ENGINE *e); - void ENGINE_register_all_RSA(void); - int ENGINE_register_DSA(ENGINE *e); - void ENGINE_unregister_DSA(ENGINE *e); - void ENGINE_register_all_DSA(void); - int ENGINE_register_ECDH(ENGINE *e); - void ENGINE_unregister_ECDH(ENGINE *e); - void ENGINE_register_all_ECDH(void); - int ENGINE_register_ECDSA(ENGINE *e); - void ENGINE_unregister_ECDSA(ENGINE *e); - void ENGINE_register_all_ECDSA(void); - int ENGINE_register_DH(ENGINE *e); - void ENGINE_unregister_DH(ENGINE *e); - void ENGINE_register_all_DH(void); - int ENGINE_register_RAND(ENGINE *e); - void ENGINE_unregister_RAND(ENGINE *e); - void ENGINE_register_all_RAND(void); - int ENGINE_register_STORE(ENGINE *e); - void ENGINE_unregister_STORE(ENGINE *e); - void ENGINE_register_all_STORE(void); - int ENGINE_register_ciphers(ENGINE *e); - void ENGINE_unregister_ciphers(ENGINE *e); - void ENGINE_register_all_ciphers(void); - int ENGINE_register_digests(ENGINE *e); - void ENGINE_unregister_digests(ENGINE *e); - void ENGINE_register_all_digests(void); - int ENGINE_register_complete(ENGINE *e); - int ENGINE_register_all_complete(void); - - int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); - int ENGINE_cmd_is_executable(ENGINE *e, int cmd); - int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, - long i, void *p, void (*f)(void), int cmd_optional); - int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, - int cmd_optional); - - int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); - void *ENGINE_get_ex_data(const ENGINE *e, int idx); - - int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - - ENGINE *ENGINE_new(void); - int ENGINE_free(ENGINE *e); - int ENGINE_up_ref(ENGINE *e); - - int ENGINE_set_id(ENGINE *e, const char *id); - int ENGINE_set_name(ENGINE *e, const char *name); - int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); - int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); - int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); - int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); - int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); - int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); - int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); - int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); - int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); - int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); - int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); - int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); - int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); - int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); - int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); - int ENGINE_set_flags(ENGINE *e, int flags); - int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); - - const char *ENGINE_get_id(const ENGINE *e); - const char *ENGINE_get_name(const ENGINE *e); - const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); - const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); - const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); - const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); - const DH_METHOD *ENGINE_get_DH(const ENGINE *e); - const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); - const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); - ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); - ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); - ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); - ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); - ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); - ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); - const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); - const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); - int ENGINE_get_flags(const ENGINE *e); - const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); - - EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, - UI_METHOD *ui_method, void *callback_data); - EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, - UI_METHOD *ui_method, void *callback_data); - - void ENGINE_add_conf_module(void); - -=head1 DESCRIPTION - -These functions create, manipulate, and use cryptographic modules in the -form of B<ENGINE> objects. These objects act as containers for -implementations of cryptographic algorithms, and support a -reference-counted mechanism to allow them to be dynamically loaded in and -out of the running application. - -The cryptographic functionality that can be provided by an B<ENGINE> -implementation includes the following abstractions; - - RSA_METHOD - for providing alternative RSA implementations - DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, - STORE_METHOD - similarly for other OpenSSL APIs - EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') - EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') - key-loading - loading public and/or private EVP_PKEY keys - -=head2 Reference counting and handles - -Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be -treated as handles - ie. not only as pointers, but also as references to -the underlying ENGINE object. Ie. one should obtain a new reference when -making copies of an ENGINE pointer if the copies will be used (and -released) independently. - -ENGINE objects have two levels of reference-counting to match the way in -which the objects are used. At the most basic level, each ENGINE pointer is -inherently a B<structural> reference - a structural reference is required -to use the pointer value at all, as this kind of reference is a guarantee -that the structure can not be deallocated until the reference is released. - -However, a structural reference provides no guarantee that the ENGINE is -initialised and able to use any of its cryptographic -implementations. Indeed it's quite possible that most ENGINEs will not -initialise at all in typical environments, as ENGINEs are typically used to -support specialised hardware. To use an ENGINE's functionality, you need a -B<functional> reference. This kind of reference can be considered a -specialised form of structural reference, because each functional reference -implicitly contains a structural reference as well - however to avoid -difficult-to-find programming bugs, it is recommended to treat the two -kinds of reference independently. If you have a functional reference to an -ENGINE, you have a guarantee that the ENGINE has been initialised ready to -perform cryptographic operations and will remain uninitialised -until after you have released your reference. - -I<Structural references> - -This basic type of reference is used for instantiating new ENGINEs, -iterating across OpenSSL's internal linked-list of loaded -ENGINEs, reading information about an ENGINE, etc. Essentially a structural -reference is sufficient if you only need to query or manipulate the data of -an ENGINE implementation rather than use its functionality. - -The ENGINE_new() function returns a structural reference to a new (empty) -ENGINE object. There are other ENGINE API functions that return structural -references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), -ENGINE_get_next(), ENGINE_get_prev(). All structural references should be -released by a corresponding to call to the ENGINE_free() function - the -ENGINE object itself will only actually be cleaned up and deallocated when -the last structural reference is released. - -It should also be noted that many ENGINE API function calls that accept a -structural reference will internally obtain another reference - typically -this happens whenever the supplied ENGINE will be needed by OpenSSL after -the function has returned. Eg. the function to add a new ENGINE to -OpenSSL's internal list is ENGINE_add() - if this function returns success, -then OpenSSL will have stored a new structural reference internally so the -caller is still responsible for freeing their own reference with -ENGINE_free() when they are finished with it. In a similar way, some -functions will automatically release the structural reference passed to it -if part of the function's job is to do so. Eg. the ENGINE_get_next() and -ENGINE_get_prev() functions are used for iterating across the internal -ENGINE list - they will return a new structural reference to the next (or -previous) ENGINE in the list or NULL if at the end (or beginning) of the -list, but in either case the structural reference passed to the function is -released on behalf of the caller. - -To clarify a particular function's handling of references, one should -always consult that function's documentation "man" page, or failing that -the openssl/engine.h header file includes some hints. - -I<Functional references> - -As mentioned, functional references exist when the cryptographic -functionality of an ENGINE is required to be available. A functional -reference can be obtained in one of two ways; from an existing structural -reference to the required ENGINE, or by asking OpenSSL for the default -operational ENGINE for a given cryptographic purpose. - -To obtain a functional reference from an existing structural reference, -call the ENGINE_init() function. This returns zero if the ENGINE was not -already operational and couldn't be successfully initialised (eg. lack of -system drivers, no special hardware attached, etc), otherwise it will -return non-zero to indicate that the ENGINE is now operational and will -have allocated a new B<functional> reference to the ENGINE. All functional -references are released by calling ENGINE_finish() (which removes the -implicit structural reference as well). - -The second way to get a functional reference is by asking OpenSSL for a -default implementation for a given task, eg. by ENGINE_get_default_RSA(), -ENGINE_get_default_cipher_engine(), etc. These are discussed in the next -section, though they are not usually required by application programmers as -they are used automatically when creating and using the relevant -algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. - -=head2 Default implementations - -For each supported abstraction, the ENGINE code maintains an internal table -of state to control which implementations are available for a given -abstraction and which should be used by default. These implementations are -registered in the tables and indexed by an 'nid' value, because -abstractions like EVP_CIPHER and EVP_DIGEST support many distinct -algorithms and modes, and ENGINEs can support arbitrarily many of them. -In the case of other abstractions like RSA, DSA, etc, there is only one -"algorithm" so all implementations implicitly register using the same 'nid' -index. - -When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. -when calling RSA_new_method(NULL)), a "get_default" call will be made to the -ENGINE subsystem to process the corresponding state table and return a -functional reference to an initialised ENGINE whose implementation should be -used. If no ENGINE should (or can) be used, it will return NULL and the caller -will operate with a NULL ENGINE handle - this usually equates to using the -conventional software implementation. In the latter case, OpenSSL will from -then on behave the way it used to before the ENGINE API existed. - -Each state table has a flag to note whether it has processed this -"get_default" query since the table was last modified, because to process -this question it must iterate across all the registered ENGINEs in the -table trying to initialise each of them in turn, in case one of them is -operational. If it returns a functional reference to an ENGINE, it will -also cache another reference to speed up processing future queries (without -needing to iterate across the table). Likewise, it will cache a NULL -response if no ENGINE was available so that future queries won't repeat the -same iteration unless the state table changes. This behaviour can also be -changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using -ENGINE_set_table_flags()), no attempted initialisations will take place, -instead the only way for the state table to return a non-NULL ENGINE to the -"get_default" query will be if one is expressly set in the table. Eg. -ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except -that it also sets the state table's cached response for the "get_default" -query. In the case of abstractions like EVP_CIPHER, where implementations are -indexed by 'nid', these flags and cached-responses are distinct for each 'nid' -value. - -=head2 Application requirements - -This section will explain the basic things an application programmer should -support to make the most useful elements of the ENGINE functionality -available to the user. The first thing to consider is whether the -programmer wishes to make alternative ENGINE modules available to the -application and user. OpenSSL maintains an internal linked list of -"visible" ENGINEs from which it has to operate - at start-up, this list is -empty and in fact if an application does not call any ENGINE API calls and -it uses static linking against openssl, then the resulting application -binary will not contain any alternative ENGINE code at all. So the first -consideration is whether any/all available ENGINE implementations should be -made visible to OpenSSL - this is controlled by calling the various "load" -functions, eg. - - /* Make ALL ENGINE implementations bundled with OpenSSL available */ - ENGINE_load_builtin_engines(); - -Note that ENGINE_load_dynamic(void) is a placeholder and does not enable -dynamic engine loading support. - -Having called any of these functions, ENGINE objects would have been -dynamically allocated and populated with these implementations and linked -into OpenSSL's internal linked list. At this point it is important to -mention an important API function; - - void ENGINE_cleanup(void); - -If no ENGINE API functions are called at all in an application, then there -are no inherent memory leaks to worry about from the ENGINE functionality, -however if any ENGINEs are loaded, even if they are never registered or -used, it is necessary to use the ENGINE_cleanup() function to -correspondingly cleanup before program exit, if the caller wishes to avoid -memory leaks. This mechanism uses an internal callback registration table -so that any ENGINE API functionality that knows it requires cleanup can -register its cleanup details to be called during ENGINE_cleanup(). This -approach allows ENGINE_cleanup() to clean up after any ENGINE functionality -at all that your program uses, yet doesn't automatically create linker -dependencies to all possible ENGINE functionality - only the cleanup -callbacks required by the functionality you do use will be required by the -linker. - -The fact that ENGINEs are made visible to OpenSSL (and thus are linked into -the program and loaded into memory at run-time) does not mean they are -"registered" or called into use by OpenSSL automatically - that behaviour -is something for the application to control. Some applications -will want to allow the user to specify exactly which ENGINE they want used -if any is to be used at all. Others may prefer to load all support and have -OpenSSL automatically use at run-time any ENGINE that is able to -successfully initialise - ie. to assume that this corresponds to -acceleration hardware attached to the machine or some such thing. There are -probably numerous other ways in which applications may prefer to handle -things, so we will simply illustrate the consequences as they apply to a -couple of simple cases and leave developers to consider these and the -source code to openssl's builtin utilities as guides. - -I<Using a specific ENGINE implementation> - -Here we'll assume an application has been configured by its user or admin -to want to use the "ACME" ENGINE if it is available in the version of -OpenSSL the application was compiled with. If it is available, it should be -used by default for all RSA, DSA, and symmetric cipher operation, otherwise -OpenSSL should use its builtin software as per usual. The following code -illustrates how to approach this; - - ENGINE *e; - const char *engine_id = "ACME"; - ENGINE_load_builtin_engines(); - e = ENGINE_by_id(engine_id); - if (!e) - /* the engine isn't available */ - return; - if (!ENGINE_init(e)) { - /* the engine couldn't initialise, release 'e' */ - ENGINE_free(e); - return; - } - if (!ENGINE_set_default_RSA(e)) - /* This should only happen when 'e' can't initialise, but the previous - * statement suggests it did. */ - abort(); - ENGINE_set_default_DSA(e); - ENGINE_set_default_ciphers(e); - /* Release the functional reference from ENGINE_init() */ - ENGINE_finish(e); - /* Release the structural reference from ENGINE_by_id() */ - ENGINE_free(e); - -I<Automatically using builtin ENGINE implementations> - -Here we'll assume we want to load and register all ENGINE implementations -bundled with OpenSSL, such that for any cryptographic algorithm required by -OpenSSL - if there is an ENGINE that implements it and can be initialise, -it should be used. The following code illustrates how this can work; - - /* Load all bundled ENGINEs into memory and make them visible */ - ENGINE_load_builtin_engines(); - /* Register all of them for every algorithm they collectively implement */ - ENGINE_register_all_complete(); - -That's all that's required. Eg. the next time OpenSSL tries to set up an -RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to -ENGINE_init() and if any of those succeed, that ENGINE will be set as the -default for RSA use from then on. - -=head2 Advanced configuration support - -There is a mechanism supported by the ENGINE framework that allows each -ENGINE implementation to define an arbitrary set of configuration -"commands" and expose them to OpenSSL and any applications based on -OpenSSL. This mechanism is entirely based on the use of name-value pairs -and assumes ASCII input (no unicode or UTF for now!), so it is ideal if -applications want to provide a transparent way for users to provide -arbitrary configuration "directives" directly to such ENGINEs. It is also -possible for the application to dynamically interrogate the loaded ENGINE -implementations for the names, descriptions, and input flags of their -available "control commands", providing a more flexible configuration -scheme. However, if the user is expected to know which ENGINE device he/she -is using (in the case of specialised hardware, this goes without saying) -then applications may not need to concern themselves with discovering the -supported control commands and simply prefer to pass settings into ENGINEs -exactly as they are provided by the user. - -Before illustrating how control commands work, it is worth mentioning what -they are typically used for. Broadly speaking there are two uses for -control commands; the first is to provide the necessary details to the -implementation (which may know nothing at all specific to the host system) -so that it can be initialised for use. This could include the path to any -driver or config files it needs to load, required network addresses, -smart-card identifiers, passwords to initialise protected devices, -logging information, etc etc. This class of commands typically needs to be -passed to an ENGINE B<before> attempting to initialise it, ie. before -calling ENGINE_init(). The other class of commands consist of settings or -operations that tweak certain behaviour or cause certain operations to take -place, and these commands may work either before or after ENGINE_init(), or -in some cases both. ENGINE implementations should provide indications of -this in the descriptions attached to builtin control commands and/or in -external product documentation. - -I<Issuing control commands to an ENGINE> - -Let's illustrate by example; a function for which the caller supplies the -name of the ENGINE it wishes to use, a table of string-pairs for use before -initialisation, and another table for use after initialisation. Note that -the string-pairs used for control commands consist of a command "name" -followed by the command "parameter" - the parameter could be NULL in some -cases but the name can not. This function should initialise the ENGINE -(issuing the "pre" commands beforehand and the "post" commands afterwards) -and set it as the default for everything except RAND and then return a -boolean success or failure. - - int - generic_load_engine_fn(const char *engine_id, - const char **pre_cmds, int pre_num, - const char **post_cmds, int post_num) - { - ENGINE *e = ENGINE_by_id(engine_id); - - if (!e) - return 0; - while (pre_num--) { - if (!ENGINE_ctrl_cmd_string(e, - pre_cmds[0], pre_cmds[1], 0)) { - fprintf(stderr, - "Failed command (%s - %s:%s)\n", - engine_id, pre_cmds[0], - pre_cmds[1] ? pre_cmds[1] : "(NULL)"); - ENGINE_free(e); - return 0; - } - pre_cmds += 2; - } - if (!ENGINE_init(e)) { - fprintf(stderr, "Failed initialisation\n"); - ENGINE_free(e); - return 0; - } - /* - * ENGINE_init() returned a functional reference, - * so free the structural reference from - * ENGINE_by_id(). - */ - ENGINE_free(e); - while (post_num--) { - if (!ENGINE_ctrl_cmd_string(e, - post_cmds[0], post_cmds[1], 0)) { - fprintf(stderr, - "Failed command (%s - %s:%s)\n", - engine_id, post_cmds[0], - post_cmds[1] ? post_cmds[1] : "(NULL)"); - ENGINE_finish(e); - return 0; - } - post_cmds += 2; - } - ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); - /* Success */ - return 1; -} - -Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can -relax the semantics of the function - if set non-zero it will only return -failure if the ENGINE supported the given command name but failed while -executing it, if the ENGINE doesn't support the command name it will simply -return success without doing anything. In this case we assume the user is -only supplying commands specific to the given ENGINE so we set this to -FALSE. - -I<Discovering supported control commands> - -It is possible to discover at run-time the names, numerical-ids, descriptions -and input parameters of the control commands supported by an ENGINE using a -structural reference. Note that some control commands are defined by OpenSSL -itself and it will intercept and handle these control commands on behalf of the -ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. -openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands -implemented by ENGINEs should be numbered from. Any command value lower than -this symbol is considered a "generic" command is handled directly by the -OpenSSL core routines. - -It is using these "core" control commands that one can discover the control -commands implemented by a given ENGINE, specifically the commands; - - #define ENGINE_HAS_CTRL_FUNCTION 10 - #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 - #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 - #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 - #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 - #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 - #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 - #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 - #define ENGINE_CTRL_GET_CMD_FLAGS 18 - -Whilst these commands are automatically processed by the OpenSSL framework code, -they use various properties exposed by each ENGINE to process these -queries. An ENGINE has 3 properties it exposes that can affect how this behaves; -it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in -the ENGINE's flags, and it can expose an array of control command descriptions. -If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will -simply pass all these "core" control commands directly to the ENGINE's ctrl() -handler (and thus, it must have supplied one), so it is up to the ENGINE to -reply to these "discovery" commands itself. If that flag is not set, then the -OpenSSL framework code will work with the following rules; - - if no ctrl() handler supplied; - ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), - all other commands fail. - if a ctrl() handler was supplied but no array of control commands; - ENGINE_HAS_CTRL_FUNCTION returns TRUE, - all other commands fail. - if a ctrl() handler and array of control commands was supplied; - ENGINE_HAS_CTRL_FUNCTION returns TRUE, - all other commands proceed processing ... - -If the ENGINE's array of control commands is empty then all other commands will -fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of -the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the -identifier of a command supported by the ENGINE and returns the next command -identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string -name for a command and returns the corresponding identifier or fails if no such -command name exists, and the remaining commands take a command identifier and -return properties of the corresponding commands. All except -ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, -or populate a supplied character buffer with a copy of the command name or -description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following -possible values; - - #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 - #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 - #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 - #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 - -If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely -informational to the caller - this flag will prevent the command being usable -for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). -"INTERNAL" commands are not intended to be exposed to text-based configuration -by applications, administrations, users, etc. These can support arbitrary -operations via ENGINE_ctrl(), including passing to and/or from the control -commands data of any arbitrary type. These commands are supported in the -discovery mechanisms simply allow applications to determine if an ENGINE -supports certain specific commands it might want to use (eg. application "foo" -might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - -and ENGINE could therefore decide whether or not to support this "foo"-specific -extension). - -=head2 Future developments - -The ENGINE API and internal architecture is currently being reviewed. Slated for -possible release in 0.9.8 is support for transparent loading of "dynamic" -ENGINEs (built as self-contained shared-libraries). This would allow ENGINE -implementations to be provided independently of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for -applications to explicitly use the "dynamic" ENGINE to bind to shared-library -implementations. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> - -=cut diff --git a/lib/libcrypto/doc/lh_stats.pod b/lib/libcrypto/doc/lh_stats.pod deleted file mode 100644 index 15f97b55455..00000000000 --- a/lib/libcrypto/doc/lh_stats.pod +++ /dev/null @@ -1,60 +0,0 @@ -=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 <openssl/lhash.h> - - 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<LHASH> 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<BIO>. - -=head1 RETURN VALUES - -These functions do not return values. - -=head1 SEE ALSO - -L<bio(3)|bio(3)>, L<lh_new(3)|lh_new(3)> - -=head1 HISTORY - -These functions are available in all versions of SSLeay and OpenSSL. - -This manpage is derived from the SSLeay documentation. - -=cut |