diff options
Diffstat (limited to 'src/lib/libcrypto/doc')
-rw-r--r-- | src/lib/libcrypto/doc/RC4.pod | 62 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/RIPEMD160.pod | 66 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/SHA1.pod | 71 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/bn.pod | 181 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/d2i_DHparams.pod | 26 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/d2i_DSAPublicKey.pod | 79 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/d2i_ECPKParameters.pod | 84 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/dh.pod | 79 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/dsa.pod | 114 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/ec.pod | 201 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/engine.pod | 599 | ||||
-rw-r--r-- | src/lib/libcrypto/doc/lh_stats.pod | 60 |
12 files changed, 0 insertions, 1622 deletions
diff --git a/src/lib/libcrypto/doc/RC4.pod b/src/lib/libcrypto/doc/RC4.pod deleted file mode 100644 index b6d3a4342c..0000000000 --- a/src/lib/libcrypto/doc/RC4.pod +++ /dev/null | |||
@@ -1,62 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RC4_set_key, RC4 - RC4 encryption | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rc4.h> | ||
10 | |||
11 | void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); | ||
12 | |||
13 | void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, | ||
14 | unsigned char *outdata); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | This library implements the Alleged RC4 cipher, which is described for | ||
19 | example in I<Applied Cryptography>. It is believed to be compatible | ||
20 | with RC4[TM], a proprietary cipher of RSA Security Inc. | ||
21 | |||
22 | RC4 is a stream cipher with variable key length. Typically, 128 bit | ||
23 | (16 byte) keys are used for strong encryption, but shorter insecure | ||
24 | key sizes have been widely used due to export restrictions. | ||
25 | |||
26 | RC4 consists of a key setup phase and the actual encryption or | ||
27 | decryption phase. | ||
28 | |||
29 | RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long | ||
30 | key at B<data>. | ||
31 | |||
32 | RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using | ||
33 | B<key> and places the result at B<outdata>. Repeated RC4() calls with | ||
34 | the same B<key> yield a continuous key stream. | ||
35 | |||
36 | Since RC4 is a stream cipher (the input is XORed with a pseudo-random | ||
37 | key stream to produce the output), decryption uses the same function | ||
38 | calls as encryption. | ||
39 | |||
40 | Applications should use the higher level functions | ||
41 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> | ||
42 | etc. instead of calling the RC4 functions directly. | ||
43 | |||
44 | =head1 RETURN VALUES | ||
45 | |||
46 | RC4_set_key() and RC4() do not return values. | ||
47 | |||
48 | =head1 NOTE | ||
49 | |||
50 | Certain conditions have to be observed to securely use stream ciphers. | ||
51 | It is not permissible to perform multiple encryptions using the same | ||
52 | key stream. | ||
53 | |||
54 | =head1 SEE ALSO | ||
55 | |||
56 | L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> | ||
57 | |||
58 | =head1 HISTORY | ||
59 | |||
60 | RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. | ||
61 | |||
62 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RIPEMD160.pod b/src/lib/libcrypto/doc/RIPEMD160.pod deleted file mode 100644 index f66fb02ed2..0000000000 --- a/src/lib/libcrypto/doc/RIPEMD160.pod +++ /dev/null | |||
@@ -1,66 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - | ||
6 | RIPEMD-160 hash function | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/ripemd.h> | ||
11 | |||
12 | unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, | ||
13 | unsigned char *md); | ||
14 | |||
15 | int RIPEMD160_Init(RIPEMD160_CTX *c); | ||
16 | int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, | ||
17 | unsigned long len); | ||
18 | int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | RIPEMD-160 is a cryptographic hash function with a | ||
23 | 160 bit output. | ||
24 | |||
25 | RIPEMD160() computes the RIPEMD-160 message digest of the B<n> | ||
26 | bytes at B<d> and places it in B<md> (which must have space for | ||
27 | RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest | ||
28 | is placed in a static array. | ||
29 | |||
30 | The following functions may be used if the message is not completely | ||
31 | stored in memory: | ||
32 | |||
33 | RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. | ||
34 | |||
35 | RIPEMD160_Update() can be called repeatedly with chunks of the message to | ||
36 | be hashed (B<len> bytes at B<data>). | ||
37 | |||
38 | RIPEMD160_Final() places the message digest in B<md>, which must have | ||
39 | space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases | ||
40 | the B<RIPEMD160_CTX>. | ||
41 | |||
42 | Applications should use the higher level functions | ||
43 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the | ||
44 | hash functions directly. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | RIPEMD160() returns a pointer to the hash value. | ||
49 | |||
50 | RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for | ||
51 | success, 0 otherwise. | ||
52 | |||
53 | =head1 CONFORMING TO | ||
54 | |||
55 | ISO/IEC 10118-3 (draft) (??) | ||
56 | |||
57 | =head1 SEE ALSO | ||
58 | |||
59 | L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
60 | |||
61 | =head1 HISTORY | ||
62 | |||
63 | RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and | ||
64 | RIPEMD160_Final() are available since SSLeay 0.9.0. | ||
65 | |||
66 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SHA1.pod b/src/lib/libcrypto/doc/SHA1.pod deleted file mode 100644 index 9fffdf59e7..0000000000 --- a/src/lib/libcrypto/doc/SHA1.pod +++ /dev/null | |||
@@ -1,71 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/sha.h> | ||
10 | |||
11 | unsigned char *SHA1(const unsigned char *d, unsigned long n, | ||
12 | unsigned char *md); | ||
13 | |||
14 | int SHA1_Init(SHA_CTX *c); | ||
15 | int SHA1_Update(SHA_CTX *c, const void *data, | ||
16 | unsigned long len); | ||
17 | int SHA1_Final(unsigned char *md, SHA_CTX *c); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a | ||
22 | 160 bit output. | ||
23 | |||
24 | SHA1() computes the SHA-1 message digest of the B<n> | ||
25 | bytes at B<d> and places it in B<md> (which must have space for | ||
26 | SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest | ||
27 | is placed in a static array. | ||
28 | |||
29 | The following functions may be used if the message is not completely | ||
30 | stored in memory: | ||
31 | |||
32 | SHA1_Init() initializes a B<SHA_CTX> structure. | ||
33 | |||
34 | SHA1_Update() can be called repeatedly with chunks of the message to | ||
35 | be hashed (B<len> bytes at B<data>). | ||
36 | |||
37 | SHA1_Final() places the message digest in B<md>, which must have space | ||
38 | for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>. | ||
39 | |||
40 | Applications should use the higher level functions | ||
41 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
42 | etc. instead of calling the hash functions directly. | ||
43 | |||
44 | The predecessor of SHA-1, SHA, is also implemented, but it should be | ||
45 | used only when backward compatibility is required. | ||
46 | |||
47 | =head1 RETURN VALUES | ||
48 | |||
49 | SHA1() returns a pointer to the hash value. | ||
50 | |||
51 | SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. | ||
52 | |||
53 | =head1 CONFORMING TO | ||
54 | |||
55 | SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash | ||
56 | Standard), | ||
57 | SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash | ||
58 | Standard), | ||
59 | ANSI X9.30 | ||
60 | |||
61 | =head1 SEE ALSO | ||
62 | |||
63 | L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, | ||
64 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
65 | |||
66 | =head1 HISTORY | ||
67 | |||
68 | SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all | ||
69 | versions of SSLeay and OpenSSL. | ||
70 | |||
71 | =cut | ||
diff --git a/src/lib/libcrypto/doc/bn.pod b/src/lib/libcrypto/doc/bn.pod deleted file mode 100644 index b3ad63320a..0000000000 --- a/src/lib/libcrypto/doc/bn.pod +++ /dev/null | |||
@@ -1,181 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | bn - multiprecision integer arithmetics | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/bn.h> | ||
10 | |||
11 | BIGNUM *BN_new(void); | ||
12 | void BN_free(BIGNUM *a); | ||
13 | void BN_init(BIGNUM *); | ||
14 | void BN_clear(BIGNUM *a); | ||
15 | void BN_clear_free(BIGNUM *a); | ||
16 | |||
17 | BN_CTX *BN_CTX_new(void); | ||
18 | void BN_CTX_init(BN_CTX *c); | ||
19 | void BN_CTX_free(BN_CTX *c); | ||
20 | |||
21 | BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); | ||
22 | BIGNUM *BN_dup(const BIGNUM *a); | ||
23 | |||
24 | BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); | ||
25 | |||
26 | int BN_num_bytes(const BIGNUM *a); | ||
27 | int BN_num_bits(const BIGNUM *a); | ||
28 | int BN_num_bits_word(BN_ULONG w); | ||
29 | |||
30 | void BN_set_negative(BIGNUM *a, int n); | ||
31 | int BN_is_negative(const BIGNUM *a); | ||
32 | |||
33 | int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); | ||
34 | int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); | ||
35 | int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
36 | int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); | ||
37 | int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, | ||
38 | BN_CTX *ctx); | ||
39 | int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
40 | int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
41 | int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
42 | BN_CTX *ctx); | ||
43 | int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
44 | BN_CTX *ctx); | ||
45 | int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
46 | BN_CTX *ctx); | ||
47 | int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
48 | int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); | ||
49 | int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
50 | const BIGNUM *m, BN_CTX *ctx); | ||
51 | int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
52 | |||
53 | int BN_add_word(BIGNUM *a, BN_ULONG w); | ||
54 | int BN_sub_word(BIGNUM *a, BN_ULONG w); | ||
55 | int BN_mul_word(BIGNUM *a, BN_ULONG w); | ||
56 | BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); | ||
57 | BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); | ||
58 | |||
59 | int BN_cmp(BIGNUM *a, BIGNUM *b); | ||
60 | int BN_ucmp(BIGNUM *a, BIGNUM *b); | ||
61 | int BN_is_zero(BIGNUM *a); | ||
62 | int BN_is_one(BIGNUM *a); | ||
63 | int BN_is_word(BIGNUM *a, BN_ULONG w); | ||
64 | int BN_is_odd(BIGNUM *a); | ||
65 | |||
66 | int BN_zero(BIGNUM *a); | ||
67 | int BN_one(BIGNUM *a); | ||
68 | const BIGNUM *BN_value_one(void); | ||
69 | int BN_set_word(BIGNUM *a, unsigned long w); | ||
70 | unsigned long BN_get_word(BIGNUM *a); | ||
71 | |||
72 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
73 | int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
74 | int BN_rand_range(BIGNUM *rnd, BIGNUM *range); | ||
75 | int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); | ||
76 | |||
77 | BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, | ||
78 | BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); | ||
79 | int BN_is_prime(const BIGNUM *p, int nchecks, | ||
80 | void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); | ||
81 | |||
82 | int BN_set_bit(BIGNUM *a, int n); | ||
83 | int BN_clear_bit(BIGNUM *a, int n); | ||
84 | int BN_is_bit_set(const BIGNUM *a, int n); | ||
85 | int BN_mask_bits(BIGNUM *a, int n); | ||
86 | int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); | ||
87 | int BN_lshift1(BIGNUM *r, BIGNUM *a); | ||
88 | int BN_rshift(BIGNUM *r, BIGNUM *a, int n); | ||
89 | int BN_rshift1(BIGNUM *r, BIGNUM *a); | ||
90 | |||
91 | int BN_bn2bin(const BIGNUM *a, unsigned char *to); | ||
92 | BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); | ||
93 | char *BN_bn2hex(const BIGNUM *a); | ||
94 | char *BN_bn2dec(const BIGNUM *a); | ||
95 | int BN_hex2bn(BIGNUM **a, const char *str); | ||
96 | int BN_dec2bn(BIGNUM **a, const char *str); | ||
97 | int BN_print(BIO *fp, const BIGNUM *a); | ||
98 | int BN_print_fp(FILE *fp, const BIGNUM *a); | ||
99 | int BN_bn2mpi(const BIGNUM *a, unsigned char *to); | ||
100 | BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); | ||
101 | |||
102 | BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, | ||
103 | BN_CTX *ctx); | ||
104 | |||
105 | BN_RECP_CTX *BN_RECP_CTX_new(void); | ||
106 | void BN_RECP_CTX_init(BN_RECP_CTX *recp); | ||
107 | void BN_RECP_CTX_free(BN_RECP_CTX *recp); | ||
108 | int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); | ||
109 | int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
110 | BN_RECP_CTX *recp, BN_CTX *ctx); | ||
111 | |||
112 | BN_MONT_CTX *BN_MONT_CTX_new(void); | ||
113 | void BN_MONT_CTX_init(BN_MONT_CTX *ctx); | ||
114 | void BN_MONT_CTX_free(BN_MONT_CTX *mont); | ||
115 | int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); | ||
116 | BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); | ||
117 | int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
118 | BN_MONT_CTX *mont, BN_CTX *ctx); | ||
119 | int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
120 | BN_CTX *ctx); | ||
121 | int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
122 | BN_CTX *ctx); | ||
123 | |||
124 | BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, | ||
125 | BIGNUM *mod); | ||
126 | void BN_BLINDING_free(BN_BLINDING *b); | ||
127 | int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); | ||
128 | int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); | ||
129 | int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); | ||
130 | int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, | ||
131 | BN_CTX *ctx); | ||
132 | int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, | ||
133 | BN_CTX *ctx); | ||
134 | unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); | ||
135 | void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); | ||
136 | unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); | ||
137 | void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); | ||
138 | BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, | ||
139 | const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, | ||
140 | int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, | ||
141 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), | ||
142 | BN_MONT_CTX *m_ctx); | ||
143 | |||
144 | =head1 DESCRIPTION | ||
145 | |||
146 | This library performs arithmetic operations on integers of arbitrary | ||
147 | size. It was written for use in public key cryptography, such as RSA | ||
148 | and Diffie-Hellman. | ||
149 | |||
150 | It uses dynamic memory allocation for storing its data structures. | ||
151 | That means that there is no limit on the size of the numbers | ||
152 | manipulated by these functions, but return values must always be | ||
153 | checked in case a memory allocation error has occurred. | ||
154 | |||
155 | The basic object in this library is a B<BIGNUM>. It is used to hold a | ||
156 | single large integer. This type should be considered opaque and fields | ||
157 | should not be modified or accessed directly. | ||
158 | |||
159 | The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; | ||
160 | L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. | ||
161 | Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> | ||
162 | describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of | ||
163 | random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime | ||
164 | numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion | ||
165 | of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. | ||
166 | |||
167 | =head1 SEE ALSO | ||
168 | |||
169 | L<bn_dump(3)|bn_dump(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, | ||
170 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<BN_new(3)|BN_new(3)>, | ||
171 | L<BN_CTX_new(3)|BN_CTX_new(3)>, L<BN_copy(3)|BN_copy(3)>, | ||
172 | L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, | ||
173 | L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, | ||
174 | L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, | ||
175 | L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, | ||
176 | L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, | ||
177 | L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, | ||
178 | L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, | ||
179 | L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> | ||
180 | |||
181 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_DHparams.pod b/src/lib/libcrypto/doc/d2i_DHparams.pod deleted file mode 100644 index 9f1aac9137..0000000000 --- a/src/lib/libcrypto/doc/d2i_DHparams.pod +++ /dev/null | |||
@@ -1,26 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH *d2i_DHparams(DH **a, unsigned char **pp, long length); | ||
12 | int i2d_DHparams(DH *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode PKCS#3 DH parameters using the | ||
17 | DHparameter structure described in PKCS#3. | ||
18 | |||
19 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
20 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
21 | |||
22 | =head1 SEE ALSO | ||
23 | |||
24 | L<d2i_X509(3)|d2i_X509(3)> | ||
25 | |||
26 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod deleted file mode 100644 index 10c49e3ad2..0000000000 --- a/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, | ||
6 | d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding | ||
7 | and parsing functions. | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/dsa.h> | ||
12 | #include <openssl/x509.h> | ||
13 | |||
14 | DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); | ||
15 | |||
16 | int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); | ||
17 | |||
18 | DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); | ||
19 | |||
20 | int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); | ||
21 | |||
22 | DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); | ||
23 | |||
24 | int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); | ||
25 | |||
26 | DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); | ||
27 | |||
28 | int i2d_DSAparams(const DSA *a, unsigned char **pp); | ||
29 | |||
30 | DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); | ||
31 | |||
32 | int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); | ||
33 | |||
34 | =head1 DESCRIPTION | ||
35 | |||
36 | d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key | ||
37 | components structure. | ||
38 | |||
39 | d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using | ||
40 | a SubjectPublicKeyInfo (certificate public key) structure. | ||
41 | |||
42 | d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key | ||
43 | components. | ||
44 | |||
45 | d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using | ||
46 | a B<Dss-Parms> structure as defined in RFC2459. | ||
47 | |||
48 | d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a | ||
49 | B<Dss-Sig-Value> structure as defined in RFC2459. | ||
50 | |||
51 | The usage of all of these functions is similar to the d2i_X509() and | ||
52 | i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
53 | |||
54 | =head1 NOTES | ||
55 | |||
56 | The B<DSA> structure passed to the private key encoding functions should have | ||
57 | all the private key components present. | ||
58 | |||
59 | The data encoded by the private key functions is unencrypted and therefore | ||
60 | offers no private key security. | ||
61 | |||
62 | The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> | ||
63 | functions when encoding public keys because they use a standard format. | ||
64 | |||
65 | The B<DSAPublicKey> functions use an non standard format the actual data encoded | ||
66 | depends on the value of the B<write_params> field of the B<a> key parameter. | ||
67 | If B<write_params> is zero then only the B<pub_key> field is encoded as an | ||
68 | B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the | ||
69 | B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. | ||
70 | |||
71 | The B<DSAPrivateKey> functions also use a non standard structure consisting | ||
72 | consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and | ||
73 | B<priv_key> fields respectively. | ||
74 | |||
75 | =head1 SEE ALSO | ||
76 | |||
77 | L<d2i_X509(3)|d2i_X509(3)> | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_ECPKParameters.pod b/src/lib/libcrypto/doc/d2i_ECPKParameters.pod deleted file mode 100644 index 704b4ab352..0000000000 --- a/src/lib/libcrypto/doc/d2i_ECPKParameters.pod +++ /dev/null | |||
@@ -1,84 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | 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 | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | |||
11 | EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); | ||
12 | int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); | ||
13 | #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) | ||
14 | #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) | ||
15 | #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ | ||
16 | (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) | ||
17 | #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ | ||
18 | (unsigned char *)(x)) | ||
19 | int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); | ||
20 | int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); | ||
21 | |||
22 | |||
23 | =head1 DESCRIPTION | ||
24 | |||
25 | The ECPKParameters encode and decode routines encode and parse the public parameters for an | ||
26 | B<EC_GROUP> structure, which represents a curve. | ||
27 | |||
28 | d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If | ||
29 | successful a pointer to the B<EC_GROUP> structure is returned. If an error | ||
30 | occurred then B<NULL> is returned. If B<px> is not B<NULL> then the | ||
31 | returned structure is written to B<*px>. If B<*px> is not B<NULL> | ||
32 | then it is assumed that B<*px> contains a valid B<EC_GROUP> | ||
33 | structure and an attempt is made to reuse it. If the call is | ||
34 | successful B<*in> is incremented to the byte following the | ||
35 | parsed data. | ||
36 | |||
37 | i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format. | ||
38 | If B<out> is not B<NULL> is writes the DER encoded data to the buffer | ||
39 | at B<*out>, and increments it to point after the data just written. | ||
40 | If the return value is negative an error occurred, otherwise it | ||
41 | returns the length of the encoded data. | ||
42 | |||
43 | If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded | ||
44 | data written to it. In this case B<*out> is not incremented and it points to | ||
45 | the start of the data just written. | ||
46 | |||
47 | d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts | ||
48 | to parse data from BIO B<bp>. | ||
49 | |||
50 | d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts | ||
51 | to parse data from FILE pointer B<fp>. | ||
52 | |||
53 | i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes | ||
54 | the encoding of the structure B<x> to BIO B<bp> and it | ||
55 | returns 1 for success and 0 for failure. | ||
56 | |||
57 | i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes | ||
58 | the encoding of the structure B<x> to BIO B<bp> and it | ||
59 | returns 1 for success and 0 for failure. | ||
60 | |||
61 | These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>, | ||
62 | where further notes and examples are available. | ||
63 | |||
64 | The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output | ||
65 | of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces. | ||
66 | |||
67 | =head1 RETURN VALUES | ||
68 | |||
69 | d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure | ||
70 | or B<NULL> if an error occurs. | ||
71 | |||
72 | i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative | ||
73 | value if an error occurs. | ||
74 | |||
75 | i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp | ||
76 | return 1 for success and 0 if an error occurs. | ||
77 | |||
78 | =head1 SEE ALSO | ||
79 | |||
80 | 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)>, | ||
81 | 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)>, | ||
82 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)> | ||
83 | |||
84 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dh.pod b/src/lib/libcrypto/doc/dh.pod deleted file mode 100644 index 5fb9890a77..0000000000 --- a/src/lib/libcrypto/doc/dh.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dh - Diffie-Hellman key agreement | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | #include <openssl/engine.h> | ||
11 | |||
12 | DH * DH_new(void); | ||
13 | void DH_free(DH *dh); | ||
14 | |||
15 | int DH_size(const DH *dh); | ||
16 | |||
17 | DH * DH_generate_parameters(int prime_len, int generator, | ||
18 | void (*callback)(int, int, void *), void *cb_arg); | ||
19 | int DH_check(const DH *dh, int *codes); | ||
20 | |||
21 | int DH_generate_key(DH *dh); | ||
22 | int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
23 | |||
24 | void DH_set_default_method(const DH_METHOD *meth); | ||
25 | const DH_METHOD *DH_get_default_method(void); | ||
26 | int DH_set_method(DH *dh, const DH_METHOD *meth); | ||
27 | DH *DH_new_method(ENGINE *engine); | ||
28 | const DH_METHOD *DH_OpenSSL(void); | ||
29 | |||
30 | int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
31 | int (*dup_func)(), void (*free_func)()); | ||
32 | int DH_set_ex_data(DH *d, int idx, char *arg); | ||
33 | char *DH_get_ex_data(DH *d, int idx); | ||
34 | |||
35 | DH * d2i_DHparams(DH **a, unsigned char **pp, long length); | ||
36 | int i2d_DHparams(const DH *a, unsigned char **pp); | ||
37 | |||
38 | int DHparams_print_fp(FILE *fp, const DH *x); | ||
39 | int DHparams_print(BIO *bp, const DH *x); | ||
40 | |||
41 | =head1 DESCRIPTION | ||
42 | |||
43 | These functions implement the Diffie-Hellman key agreement protocol. The | ||
44 | generation of shared DH parameters is described in | ||
45 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>; | ||
46 | L<DH_generate_key(3)|DH_generate_key(3)> describes how to perform a key | ||
47 | agreement. | ||
48 | |||
49 | The B<DH> structure consists of several BIGNUM components. | ||
50 | |||
51 | struct | ||
52 | { | ||
53 | BIGNUM *p; // prime number (shared) | ||
54 | BIGNUM *g; // generator of Z_p (shared) | ||
55 | BIGNUM *priv_key; // private DH value x | ||
56 | BIGNUM *pub_key; // public DH value g^x | ||
57 | // ... | ||
58 | }; | ||
59 | DH | ||
60 | |||
61 | Note that DH keys may use non-standard B<DH_METHOD> implementations, | ||
62 | either directly or by the use of B<ENGINE> modules. In some cases (eg. an | ||
63 | ENGINE providing support for hardware-embedded keys), these BIGNUM values | ||
64 | will not be used by the implementation or may be used for alternative data | ||
65 | storage. For this reason, applications should generally avoid using DH | ||
66 | structure elements directly and instead use API functions to query or | ||
67 | modify keys. | ||
68 | |||
69 | =head1 SEE ALSO | ||
70 | |||
71 | L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, | ||
72 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, | ||
73 | L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, | ||
74 | L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, | ||
75 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>, | ||
76 | L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, | ||
77 | L<RSA_print(3)|RSA_print(3)> | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dsa.pod b/src/lib/libcrypto/doc/dsa.pod deleted file mode 100644 index da07d2b930..0000000000 --- a/src/lib/libcrypto/doc/dsa.pod +++ /dev/null | |||
@@ -1,114 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dsa - Digital Signature Algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | #include <openssl/engine.h> | ||
11 | |||
12 | DSA * DSA_new(void); | ||
13 | void DSA_free(DSA *dsa); | ||
14 | |||
15 | int DSA_size(const DSA *dsa); | ||
16 | |||
17 | DSA * DSA_generate_parameters(int bits, unsigned char *seed, | ||
18 | int seed_len, int *counter_ret, unsigned long *h_ret, | ||
19 | void (*callback)(int, int, void *), void *cb_arg); | ||
20 | |||
21 | DH * DSA_dup_DH(const DSA *r); | ||
22 | |||
23 | int DSA_generate_key(DSA *dsa); | ||
24 | |||
25 | int DSA_sign(int dummy, const unsigned char *dgst, int len, | ||
26 | unsigned char *sigret, unsigned int *siglen, DSA *dsa); | ||
27 | int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, | ||
28 | BIGNUM **rp); | ||
29 | int DSA_verify(int dummy, const unsigned char *dgst, int len, | ||
30 | const unsigned char *sigbuf, int siglen, DSA *dsa); | ||
31 | |||
32 | void DSA_set_default_method(const DSA_METHOD *meth); | ||
33 | const DSA_METHOD *DSA_get_default_method(void); | ||
34 | int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); | ||
35 | DSA *DSA_new_method(ENGINE *engine); | ||
36 | const DSA_METHOD *DSA_OpenSSL(void); | ||
37 | |||
38 | int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
39 | int (*dup_func)(), void (*free_func)()); | ||
40 | int DSA_set_ex_data(DSA *d, int idx, char *arg); | ||
41 | char *DSA_get_ex_data(DSA *d, int idx); | ||
42 | |||
43 | DSA_SIG *DSA_SIG_new(void); | ||
44 | void DSA_SIG_free(DSA_SIG *a); | ||
45 | int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); | ||
46 | DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); | ||
47 | |||
48 | DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); | ||
49 | int DSA_do_verify(const unsigned char *dgst, int dgst_len, | ||
50 | DSA_SIG *sig, DSA *dsa); | ||
51 | |||
52 | DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); | ||
53 | DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); | ||
54 | DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); | ||
55 | int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); | ||
56 | int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); | ||
57 | int i2d_DSAparams(const DSA *a,unsigned char **pp); | ||
58 | |||
59 | int DSAparams_print(BIO *bp, const DSA *x); | ||
60 | int DSAparams_print_fp(FILE *fp, const DSA *x); | ||
61 | int DSA_print(BIO *bp, const DSA *x, int off); | ||
62 | int DSA_print_fp(FILE *bp, const DSA *x, int off); | ||
63 | |||
64 | =head1 DESCRIPTION | ||
65 | |||
66 | These functions implement the Digital Signature Algorithm (DSA). The | ||
67 | generation of shared DSA parameters is described in | ||
68 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; | ||
69 | L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to | ||
70 | generate a signature key. Signature generation and verification are | ||
71 | described in L<DSA_sign(3)|DSA_sign(3)>. | ||
72 | |||
73 | The B<DSA> structure consists of several BIGNUM components. | ||
74 | |||
75 | struct | ||
76 | { | ||
77 | BIGNUM *p; // prime number (public) | ||
78 | BIGNUM *q; // 160-bit subprime, q | p-1 (public) | ||
79 | BIGNUM *g; // generator of subgroup (public) | ||
80 | BIGNUM *priv_key; // private key x | ||
81 | BIGNUM *pub_key; // public key y = g^x | ||
82 | // ... | ||
83 | } | ||
84 | DSA; | ||
85 | |||
86 | In public keys, B<priv_key> is NULL. | ||
87 | |||
88 | Note that DSA keys may use non-standard B<DSA_METHOD> implementations, | ||
89 | either directly or by the use of B<ENGINE> modules. In some cases (eg. an | ||
90 | ENGINE providing support for hardware-embedded keys), these BIGNUM values | ||
91 | will not be used by the implementation or may be used for alternative data | ||
92 | storage. For this reason, applications should generally avoid using DSA | ||
93 | structure elements directly and instead use API functions to query or | ||
94 | modify keys. | ||
95 | |||
96 | =head1 CONFORMING TO | ||
97 | |||
98 | US Federal Information Processing Standard FIPS 186 (Digital Signature | ||
99 | Standard, DSS), ANSI X9.30 | ||
100 | |||
101 | =head1 SEE ALSO | ||
102 | |||
103 | L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
104 | L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, | ||
105 | L<DSA_new(3)|DSA_new(3)>, | ||
106 | L<DSA_size(3)|DSA_size(3)>, | ||
107 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, | ||
108 | L<DSA_dup_DH(3)|DSA_dup_DH(3)>, | ||
109 | L<DSA_generate_key(3)|DSA_generate_key(3)>, | ||
110 | L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, | ||
111 | L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, | ||
112 | L<RSA_print(3)|RSA_print(3)> | ||
113 | |||
114 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ec.pod b/src/lib/libcrypto/doc/ec.pod deleted file mode 100644 index 891948e4f6..0000000000 --- a/src/lib/libcrypto/doc/ec.pod +++ /dev/null | |||
@@ -1,201 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ec - Elliptic Curve functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | const EC_METHOD *EC_GFp_simple_method(void); | ||
13 | const EC_METHOD *EC_GFp_mont_method(void); | ||
14 | const EC_METHOD *EC_GFp_nist_method(void); | ||
15 | const EC_METHOD *EC_GFp_nistp224_method(void); | ||
16 | const EC_METHOD *EC_GFp_nistp256_method(void); | ||
17 | const EC_METHOD *EC_GFp_nistp521_method(void); | ||
18 | |||
19 | const EC_METHOD *EC_GF2m_simple_method(void); | ||
20 | |||
21 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); | ||
22 | void EC_GROUP_free(EC_GROUP *group); | ||
23 | void EC_GROUP_clear_free(EC_GROUP *group); | ||
24 | int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); | ||
25 | EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); | ||
26 | const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); | ||
27 | int EC_METHOD_get_field_type(const EC_METHOD *meth); | ||
28 | int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); | ||
29 | const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); | ||
30 | int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); | ||
31 | int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); | ||
32 | void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); | ||
33 | int EC_GROUP_get_curve_name(const EC_GROUP *group); | ||
34 | void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); | ||
35 | int EC_GROUP_get_asn1_flag(const EC_GROUP *group); | ||
36 | void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); | ||
37 | point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); | ||
38 | unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); | ||
39 | size_t EC_GROUP_get_seed_len(const EC_GROUP *); | ||
40 | size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); | ||
41 | int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
42 | int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
43 | int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
44 | int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
45 | int EC_GROUP_get_degree(const EC_GROUP *group); | ||
46 | int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); | ||
47 | int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); | ||
48 | int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); | ||
49 | EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
50 | EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
51 | EC_GROUP *EC_GROUP_new_by_curve_name(int nid); | ||
52 | |||
53 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); | ||
54 | |||
55 | EC_POINT *EC_POINT_new(const EC_GROUP *group); | ||
56 | void EC_POINT_free(EC_POINT *point); | ||
57 | void EC_POINT_clear_free(EC_POINT *point); | ||
58 | int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); | ||
59 | EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); | ||
60 | const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); | ||
61 | int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); | ||
62 | int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
63 | const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); | ||
64 | int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, | ||
65 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); | ||
66 | int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
67 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
68 | int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, | ||
69 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
70 | int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
71 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
72 | int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
73 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
74 | int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, | ||
75 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
76 | int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
77 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
78 | size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, | ||
79 | point_conversion_form_t form, | ||
80 | unsigned char *buf, size_t len, BN_CTX *ctx); | ||
81 | int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, | ||
82 | const unsigned char *buf, size_t len, BN_CTX *ctx); | ||
83 | BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, | ||
84 | point_conversion_form_t form, BIGNUM *, BN_CTX *); | ||
85 | EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, | ||
86 | EC_POINT *, BN_CTX *); | ||
87 | char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, | ||
88 | point_conversion_form_t form, BN_CTX *); | ||
89 | EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, | ||
90 | EC_POINT *, BN_CTX *); | ||
91 | |||
92 | int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
93 | int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); | ||
94 | int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); | ||
95 | int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); | ||
96 | int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); | ||
97 | int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
98 | int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); | ||
99 | int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); | ||
100 | 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); | ||
101 | int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); | ||
102 | int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); | ||
103 | int EC_GROUP_have_precompute_mult(const EC_GROUP *group); | ||
104 | |||
105 | int EC_GROUP_get_basis_type(const EC_GROUP *); | ||
106 | int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); | ||
107 | int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, | ||
108 | unsigned int *k2, unsigned int *k3); | ||
109 | EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); | ||
110 | int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); | ||
111 | #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) | ||
112 | #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) | ||
113 | #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ | ||
114 | (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) | ||
115 | #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ | ||
116 | (unsigned char *)(x)) | ||
117 | int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); | ||
118 | int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); | ||
119 | |||
120 | EC_KEY *EC_KEY_new(void); | ||
121 | int EC_KEY_get_flags(const EC_KEY *key); | ||
122 | void EC_KEY_set_flags(EC_KEY *key, int flags); | ||
123 | void EC_KEY_clear_flags(EC_KEY *key, int flags); | ||
124 | EC_KEY *EC_KEY_new_by_curve_name(int nid); | ||
125 | void EC_KEY_free(EC_KEY *key); | ||
126 | EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); | ||
127 | EC_KEY *EC_KEY_dup(const EC_KEY *src); | ||
128 | int EC_KEY_up_ref(EC_KEY *key); | ||
129 | const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); | ||
130 | int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); | ||
131 | const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); | ||
132 | int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); | ||
133 | const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); | ||
134 | int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); | ||
135 | unsigned EC_KEY_get_enc_flags(const EC_KEY *key); | ||
136 | void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); | ||
137 | point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); | ||
138 | void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); | ||
139 | void *EC_KEY_get_key_method_data(EC_KEY *key, | ||
140 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
141 | void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, | ||
142 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
143 | void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); | ||
144 | int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); | ||
145 | int EC_KEY_generate_key(EC_KEY *key); | ||
146 | int EC_KEY_check_key(const EC_KEY *key); | ||
147 | int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); | ||
148 | |||
149 | EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); | ||
150 | int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); | ||
151 | |||
152 | EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); | ||
153 | int i2d_ECParameters(EC_KEY *key, unsigned char **out); | ||
154 | |||
155 | EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); | ||
156 | int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); | ||
157 | int ECParameters_print(BIO *bp, const EC_KEY *key); | ||
158 | int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); | ||
159 | int ECParameters_print_fp(FILE *fp, const EC_KEY *key); | ||
160 | int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); | ||
161 | EC_KEY *ECParameters_dup(EC_KEY *key); | ||
162 | #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \ | ||
163 | EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \ | ||
164 | EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) | ||
165 | |||
166 | |||
167 | =head1 DESCRIPTION | ||
168 | |||
169 | This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. | ||
170 | In general an elliptic curve is one with an equation of the form: | ||
171 | |||
172 | y^2 = x^3 + ax + b | ||
173 | |||
174 | An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an | ||
175 | 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 | ||
176 | public key is a point on a curve (represented by an B<EC_POINT>). | ||
177 | |||
178 | The library contains a number of alternative implementations of the different functions. Each implementation is optimised | ||
179 | for different scenarios. No matter which implementation is being used, the interface remains the same. The library | ||
180 | handles calling the correct implementation when an interface function is invoked. An implementation is represented by | ||
181 | an B<EC_METHOD> structure. | ||
182 | |||
183 | The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>. Functions for | ||
184 | manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>. | ||
185 | |||
186 | Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>, | ||
187 | whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>. | ||
188 | |||
189 | For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in | ||
190 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>. | ||
191 | |||
192 | For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>. | ||
193 | |||
194 | =head1 SEE ALSO | ||
195 | |||
196 | L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
197 | 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)>, | ||
198 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
199 | |||
200 | |||
201 | =cut | ||
diff --git a/src/lib/libcrypto/doc/engine.pod b/src/lib/libcrypto/doc/engine.pod deleted file mode 100644 index 31035af398..0000000000 --- a/src/lib/libcrypto/doc/engine.pod +++ /dev/null | |||
@@ -1,599 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ENGINE_add, ENGINE_by_id, ENGINE_finish, ENGINE_get_first, | ||
6 | ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, | ||
7 | ENGINE_init, ENGINE_load_builtin_engines, ENGINE_remove | ||
8 | - ENGINE cryptographic module support | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/engine.h> | ||
13 | |||
14 | ENGINE *ENGINE_get_first(void); | ||
15 | ENGINE *ENGINE_get_last(void); | ||
16 | ENGINE *ENGINE_get_next(ENGINE *e); | ||
17 | ENGINE *ENGINE_get_prev(ENGINE *e); | ||
18 | |||
19 | int ENGINE_add(ENGINE *e); | ||
20 | int ENGINE_remove(ENGINE *e); | ||
21 | |||
22 | ENGINE *ENGINE_by_id(const char *id); | ||
23 | |||
24 | int ENGINE_init(ENGINE *e); | ||
25 | int ENGINE_finish(ENGINE *e); | ||
26 | |||
27 | void ENGINE_load_openssl(void); | ||
28 | void ENGINE_load_dynamic(void); | ||
29 | void ENGINE_load_cryptodev(void); | ||
30 | void ENGINE_load_builtin_engines(void); | ||
31 | |||
32 | void ENGINE_cleanup(void); | ||
33 | |||
34 | ENGINE *ENGINE_get_default_RSA(void); | ||
35 | ENGINE *ENGINE_get_default_DSA(void); | ||
36 | ENGINE *ENGINE_get_default_ECDH(void); | ||
37 | ENGINE *ENGINE_get_default_ECDSA(void); | ||
38 | ENGINE *ENGINE_get_default_DH(void); | ||
39 | ENGINE *ENGINE_get_default_RAND(void); | ||
40 | ENGINE *ENGINE_get_cipher_engine(int nid); | ||
41 | ENGINE *ENGINE_get_digest_engine(int nid); | ||
42 | |||
43 | int ENGINE_set_default_RSA(ENGINE *e); | ||
44 | int ENGINE_set_default_DSA(ENGINE *e); | ||
45 | int ENGINE_set_default_ECDH(ENGINE *e); | ||
46 | int ENGINE_set_default_ECDSA(ENGINE *e); | ||
47 | int ENGINE_set_default_DH(ENGINE *e); | ||
48 | int ENGINE_set_default_RAND(ENGINE *e); | ||
49 | int ENGINE_set_default_ciphers(ENGINE *e); | ||
50 | int ENGINE_set_default_digests(ENGINE *e); | ||
51 | int ENGINE_set_default_string(ENGINE *e, const char *list); | ||
52 | |||
53 | int ENGINE_set_default(ENGINE *e, unsigned int flags); | ||
54 | |||
55 | unsigned int ENGINE_get_table_flags(void); | ||
56 | void ENGINE_set_table_flags(unsigned int flags); | ||
57 | |||
58 | int ENGINE_register_RSA(ENGINE *e); | ||
59 | void ENGINE_unregister_RSA(ENGINE *e); | ||
60 | void ENGINE_register_all_RSA(void); | ||
61 | int ENGINE_register_DSA(ENGINE *e); | ||
62 | void ENGINE_unregister_DSA(ENGINE *e); | ||
63 | void ENGINE_register_all_DSA(void); | ||
64 | int ENGINE_register_ECDH(ENGINE *e); | ||
65 | void ENGINE_unregister_ECDH(ENGINE *e); | ||
66 | void ENGINE_register_all_ECDH(void); | ||
67 | int ENGINE_register_ECDSA(ENGINE *e); | ||
68 | void ENGINE_unregister_ECDSA(ENGINE *e); | ||
69 | void ENGINE_register_all_ECDSA(void); | ||
70 | int ENGINE_register_DH(ENGINE *e); | ||
71 | void ENGINE_unregister_DH(ENGINE *e); | ||
72 | void ENGINE_register_all_DH(void); | ||
73 | int ENGINE_register_RAND(ENGINE *e); | ||
74 | void ENGINE_unregister_RAND(ENGINE *e); | ||
75 | void ENGINE_register_all_RAND(void); | ||
76 | int ENGINE_register_STORE(ENGINE *e); | ||
77 | void ENGINE_unregister_STORE(ENGINE *e); | ||
78 | void ENGINE_register_all_STORE(void); | ||
79 | int ENGINE_register_ciphers(ENGINE *e); | ||
80 | void ENGINE_unregister_ciphers(ENGINE *e); | ||
81 | void ENGINE_register_all_ciphers(void); | ||
82 | int ENGINE_register_digests(ENGINE *e); | ||
83 | void ENGINE_unregister_digests(ENGINE *e); | ||
84 | void ENGINE_register_all_digests(void); | ||
85 | int ENGINE_register_complete(ENGINE *e); | ||
86 | int ENGINE_register_all_complete(void); | ||
87 | |||
88 | int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); | ||
89 | int ENGINE_cmd_is_executable(ENGINE *e, int cmd); | ||
90 | int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, | ||
91 | long i, void *p, void (*f)(void), int cmd_optional); | ||
92 | int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, | ||
93 | int cmd_optional); | ||
94 | |||
95 | int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); | ||
96 | void *ENGINE_get_ex_data(const ENGINE *e, int idx); | ||
97 | |||
98 | int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, | ||
99 | CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); | ||
100 | |||
101 | ENGINE *ENGINE_new(void); | ||
102 | int ENGINE_free(ENGINE *e); | ||
103 | int ENGINE_up_ref(ENGINE *e); | ||
104 | |||
105 | int ENGINE_set_id(ENGINE *e, const char *id); | ||
106 | int ENGINE_set_name(ENGINE *e, const char *name); | ||
107 | int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); | ||
108 | int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); | ||
109 | int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); | ||
110 | int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); | ||
111 | int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); | ||
112 | int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); | ||
113 | int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); | ||
114 | int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); | ||
115 | int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); | ||
116 | int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); | ||
117 | int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); | ||
118 | int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); | ||
119 | int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); | ||
120 | int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); | ||
121 | int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); | ||
122 | int ENGINE_set_flags(ENGINE *e, int flags); | ||
123 | int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); | ||
124 | |||
125 | const char *ENGINE_get_id(const ENGINE *e); | ||
126 | const char *ENGINE_get_name(const ENGINE *e); | ||
127 | const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); | ||
128 | const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); | ||
129 | const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); | ||
130 | const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); | ||
131 | const DH_METHOD *ENGINE_get_DH(const ENGINE *e); | ||
132 | const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); | ||
133 | const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); | ||
134 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); | ||
135 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); | ||
136 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); | ||
137 | ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); | ||
138 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); | ||
139 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); | ||
140 | ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); | ||
141 | ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); | ||
142 | const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); | ||
143 | const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); | ||
144 | int ENGINE_get_flags(const ENGINE *e); | ||
145 | const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); | ||
146 | |||
147 | EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, | ||
148 | UI_METHOD *ui_method, void *callback_data); | ||
149 | EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, | ||
150 | UI_METHOD *ui_method, void *callback_data); | ||
151 | |||
152 | void ENGINE_add_conf_module(void); | ||
153 | |||
154 | =head1 DESCRIPTION | ||
155 | |||
156 | These functions create, manipulate, and use cryptographic modules in the | ||
157 | form of B<ENGINE> objects. These objects act as containers for | ||
158 | implementations of cryptographic algorithms, and support a | ||
159 | reference-counted mechanism to allow them to be dynamically loaded in and | ||
160 | out of the running application. | ||
161 | |||
162 | The cryptographic functionality that can be provided by an B<ENGINE> | ||
163 | implementation includes the following abstractions; | ||
164 | |||
165 | RSA_METHOD - for providing alternative RSA implementations | ||
166 | DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, | ||
167 | STORE_METHOD - similarly for other OpenSSL APIs | ||
168 | EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') | ||
169 | EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') | ||
170 | key-loading - loading public and/or private EVP_PKEY keys | ||
171 | |||
172 | =head2 Reference counting and handles | ||
173 | |||
174 | Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be | ||
175 | treated as handles - ie. not only as pointers, but also as references to | ||
176 | the underlying ENGINE object. Ie. one should obtain a new reference when | ||
177 | making copies of an ENGINE pointer if the copies will be used (and | ||
178 | released) independently. | ||
179 | |||
180 | ENGINE objects have two levels of reference-counting to match the way in | ||
181 | which the objects are used. At the most basic level, each ENGINE pointer is | ||
182 | inherently a B<structural> reference - a structural reference is required | ||
183 | to use the pointer value at all, as this kind of reference is a guarantee | ||
184 | that the structure can not be deallocated until the reference is released. | ||
185 | |||
186 | However, a structural reference provides no guarantee that the ENGINE is | ||
187 | initialised and able to use any of its cryptographic | ||
188 | implementations. Indeed it's quite possible that most ENGINEs will not | ||
189 | initialise at all in typical environments, as ENGINEs are typically used to | ||
190 | support specialised hardware. To use an ENGINE's functionality, you need a | ||
191 | B<functional> reference. This kind of reference can be considered a | ||
192 | specialised form of structural reference, because each functional reference | ||
193 | implicitly contains a structural reference as well - however to avoid | ||
194 | difficult-to-find programming bugs, it is recommended to treat the two | ||
195 | kinds of reference independently. If you have a functional reference to an | ||
196 | ENGINE, you have a guarantee that the ENGINE has been initialised ready to | ||
197 | perform cryptographic operations and will remain uninitialised | ||
198 | until after you have released your reference. | ||
199 | |||
200 | I<Structural references> | ||
201 | |||
202 | This basic type of reference is used for instantiating new ENGINEs, | ||
203 | iterating across OpenSSL's internal linked-list of loaded | ||
204 | ENGINEs, reading information about an ENGINE, etc. Essentially a structural | ||
205 | reference is sufficient if you only need to query or manipulate the data of | ||
206 | an ENGINE implementation rather than use its functionality. | ||
207 | |||
208 | The ENGINE_new() function returns a structural reference to a new (empty) | ||
209 | ENGINE object. There are other ENGINE API functions that return structural | ||
210 | references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), | ||
211 | ENGINE_get_next(), ENGINE_get_prev(). All structural references should be | ||
212 | released by a corresponding to call to the ENGINE_free() function - the | ||
213 | ENGINE object itself will only actually be cleaned up and deallocated when | ||
214 | the last structural reference is released. | ||
215 | |||
216 | It should also be noted that many ENGINE API function calls that accept a | ||
217 | structural reference will internally obtain another reference - typically | ||
218 | this happens whenever the supplied ENGINE will be needed by OpenSSL after | ||
219 | the function has returned. Eg. the function to add a new ENGINE to | ||
220 | OpenSSL's internal list is ENGINE_add() - if this function returns success, | ||
221 | then OpenSSL will have stored a new structural reference internally so the | ||
222 | caller is still responsible for freeing their own reference with | ||
223 | ENGINE_free() when they are finished with it. In a similar way, some | ||
224 | functions will automatically release the structural reference passed to it | ||
225 | if part of the function's job is to do so. Eg. the ENGINE_get_next() and | ||
226 | ENGINE_get_prev() functions are used for iterating across the internal | ||
227 | ENGINE list - they will return a new structural reference to the next (or | ||
228 | previous) ENGINE in the list or NULL if at the end (or beginning) of the | ||
229 | list, but in either case the structural reference passed to the function is | ||
230 | released on behalf of the caller. | ||
231 | |||
232 | To clarify a particular function's handling of references, one should | ||
233 | always consult that function's documentation "man" page, or failing that | ||
234 | the openssl/engine.h header file includes some hints. | ||
235 | |||
236 | I<Functional references> | ||
237 | |||
238 | As mentioned, functional references exist when the cryptographic | ||
239 | functionality of an ENGINE is required to be available. A functional | ||
240 | reference can be obtained in one of two ways; from an existing structural | ||
241 | reference to the required ENGINE, or by asking OpenSSL for the default | ||
242 | operational ENGINE for a given cryptographic purpose. | ||
243 | |||
244 | To obtain a functional reference from an existing structural reference, | ||
245 | call the ENGINE_init() function. This returns zero if the ENGINE was not | ||
246 | already operational and couldn't be successfully initialised (eg. lack of | ||
247 | system drivers, no special hardware attached, etc), otherwise it will | ||
248 | return non-zero to indicate that the ENGINE is now operational and will | ||
249 | have allocated a new B<functional> reference to the ENGINE. All functional | ||
250 | references are released by calling ENGINE_finish() (which removes the | ||
251 | implicit structural reference as well). | ||
252 | |||
253 | The second way to get a functional reference is by asking OpenSSL for a | ||
254 | default implementation for a given task, eg. by ENGINE_get_default_RSA(), | ||
255 | ENGINE_get_default_cipher_engine(), etc. These are discussed in the next | ||
256 | section, though they are not usually required by application programmers as | ||
257 | they are used automatically when creating and using the relevant | ||
258 | algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. | ||
259 | |||
260 | =head2 Default implementations | ||
261 | |||
262 | For each supported abstraction, the ENGINE code maintains an internal table | ||
263 | of state to control which implementations are available for a given | ||
264 | abstraction and which should be used by default. These implementations are | ||
265 | registered in the tables and indexed by an 'nid' value, because | ||
266 | abstractions like EVP_CIPHER and EVP_DIGEST support many distinct | ||
267 | algorithms and modes, and ENGINEs can support arbitrarily many of them. | ||
268 | In the case of other abstractions like RSA, DSA, etc, there is only one | ||
269 | "algorithm" so all implementations implicitly register using the same 'nid' | ||
270 | index. | ||
271 | |||
272 | When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. | ||
273 | when calling RSA_new_method(NULL)), a "get_default" call will be made to the | ||
274 | ENGINE subsystem to process the corresponding state table and return a | ||
275 | functional reference to an initialised ENGINE whose implementation should be | ||
276 | used. If no ENGINE should (or can) be used, it will return NULL and the caller | ||
277 | will operate with a NULL ENGINE handle - this usually equates to using the | ||
278 | conventional software implementation. In the latter case, OpenSSL will from | ||
279 | then on behave the way it used to before the ENGINE API existed. | ||
280 | |||
281 | Each state table has a flag to note whether it has processed this | ||
282 | "get_default" query since the table was last modified, because to process | ||
283 | this question it must iterate across all the registered ENGINEs in the | ||
284 | table trying to initialise each of them in turn, in case one of them is | ||
285 | operational. If it returns a functional reference to an ENGINE, it will | ||
286 | also cache another reference to speed up processing future queries (without | ||
287 | needing to iterate across the table). Likewise, it will cache a NULL | ||
288 | response if no ENGINE was available so that future queries won't repeat the | ||
289 | same iteration unless the state table changes. This behaviour can also be | ||
290 | changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using | ||
291 | ENGINE_set_table_flags()), no attempted initialisations will take place, | ||
292 | instead the only way for the state table to return a non-NULL ENGINE to the | ||
293 | "get_default" query will be if one is expressly set in the table. Eg. | ||
294 | ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except | ||
295 | that it also sets the state table's cached response for the "get_default" | ||
296 | query. In the case of abstractions like EVP_CIPHER, where implementations are | ||
297 | indexed by 'nid', these flags and cached-responses are distinct for each 'nid' | ||
298 | value. | ||
299 | |||
300 | =head2 Application requirements | ||
301 | |||
302 | This section will explain the basic things an application programmer should | ||
303 | support to make the most useful elements of the ENGINE functionality | ||
304 | available to the user. The first thing to consider is whether the | ||
305 | programmer wishes to make alternative ENGINE modules available to the | ||
306 | application and user. OpenSSL maintains an internal linked list of | ||
307 | "visible" ENGINEs from which it has to operate - at start-up, this list is | ||
308 | empty and in fact if an application does not call any ENGINE API calls and | ||
309 | it uses static linking against openssl, then the resulting application | ||
310 | binary will not contain any alternative ENGINE code at all. So the first | ||
311 | consideration is whether any/all available ENGINE implementations should be | ||
312 | made visible to OpenSSL - this is controlled by calling the various "load" | ||
313 | functions, eg. | ||
314 | |||
315 | /* Make ALL ENGINE implementations bundled with OpenSSL available */ | ||
316 | ENGINE_load_builtin_engines(); | ||
317 | |||
318 | Note that ENGINE_load_dynamic(void) is a placeholder and does not enable | ||
319 | dynamic engine loading support. | ||
320 | |||
321 | Having called any of these functions, ENGINE objects would have been | ||
322 | dynamically allocated and populated with these implementations and linked | ||
323 | into OpenSSL's internal linked list. At this point it is important to | ||
324 | mention an important API function; | ||
325 | |||
326 | void ENGINE_cleanup(void); | ||
327 | |||
328 | If no ENGINE API functions are called at all in an application, then there | ||
329 | are no inherent memory leaks to worry about from the ENGINE functionality, | ||
330 | however if any ENGINEs are loaded, even if they are never registered or | ||
331 | used, it is necessary to use the ENGINE_cleanup() function to | ||
332 | correspondingly cleanup before program exit, if the caller wishes to avoid | ||
333 | memory leaks. This mechanism uses an internal callback registration table | ||
334 | so that any ENGINE API functionality that knows it requires cleanup can | ||
335 | register its cleanup details to be called during ENGINE_cleanup(). This | ||
336 | approach allows ENGINE_cleanup() to clean up after any ENGINE functionality | ||
337 | at all that your program uses, yet doesn't automatically create linker | ||
338 | dependencies to all possible ENGINE functionality - only the cleanup | ||
339 | callbacks required by the functionality you do use will be required by the | ||
340 | linker. | ||
341 | |||
342 | The fact that ENGINEs are made visible to OpenSSL (and thus are linked into | ||
343 | the program and loaded into memory at run-time) does not mean they are | ||
344 | "registered" or called into use by OpenSSL automatically - that behaviour | ||
345 | is something for the application to control. Some applications | ||
346 | will want to allow the user to specify exactly which ENGINE they want used | ||
347 | if any is to be used at all. Others may prefer to load all support and have | ||
348 | OpenSSL automatically use at run-time any ENGINE that is able to | ||
349 | successfully initialise - ie. to assume that this corresponds to | ||
350 | acceleration hardware attached to the machine or some such thing. There are | ||
351 | probably numerous other ways in which applications may prefer to handle | ||
352 | things, so we will simply illustrate the consequences as they apply to a | ||
353 | couple of simple cases and leave developers to consider these and the | ||
354 | source code to openssl's builtin utilities as guides. | ||
355 | |||
356 | I<Using a specific ENGINE implementation> | ||
357 | |||
358 | Here we'll assume an application has been configured by its user or admin | ||
359 | to want to use the "ACME" ENGINE if it is available in the version of | ||
360 | OpenSSL the application was compiled with. If it is available, it should be | ||
361 | used by default for all RSA, DSA, and symmetric cipher operation, otherwise | ||
362 | OpenSSL should use its builtin software as per usual. The following code | ||
363 | illustrates how to approach this; | ||
364 | |||
365 | ENGINE *e; | ||
366 | const char *engine_id = "ACME"; | ||
367 | ENGINE_load_builtin_engines(); | ||
368 | e = ENGINE_by_id(engine_id); | ||
369 | if (!e) | ||
370 | /* the engine isn't available */ | ||
371 | return; | ||
372 | if (!ENGINE_init(e)) { | ||
373 | /* the engine couldn't initialise, release 'e' */ | ||
374 | ENGINE_free(e); | ||
375 | return; | ||
376 | } | ||
377 | if (!ENGINE_set_default_RSA(e)) | ||
378 | /* This should only happen when 'e' can't initialise, but the previous | ||
379 | * statement suggests it did. */ | ||
380 | abort(); | ||
381 | ENGINE_set_default_DSA(e); | ||
382 | ENGINE_set_default_ciphers(e); | ||
383 | /* Release the functional reference from ENGINE_init() */ | ||
384 | ENGINE_finish(e); | ||
385 | /* Release the structural reference from ENGINE_by_id() */ | ||
386 | ENGINE_free(e); | ||
387 | |||
388 | I<Automatically using builtin ENGINE implementations> | ||
389 | |||
390 | Here we'll assume we want to load and register all ENGINE implementations | ||
391 | bundled with OpenSSL, such that for any cryptographic algorithm required by | ||
392 | OpenSSL - if there is an ENGINE that implements it and can be initialise, | ||
393 | it should be used. The following code illustrates how this can work; | ||
394 | |||
395 | /* Load all bundled ENGINEs into memory and make them visible */ | ||
396 | ENGINE_load_builtin_engines(); | ||
397 | /* Register all of them for every algorithm they collectively implement */ | ||
398 | ENGINE_register_all_complete(); | ||
399 | |||
400 | That's all that's required. Eg. the next time OpenSSL tries to set up an | ||
401 | RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to | ||
402 | ENGINE_init() and if any of those succeed, that ENGINE will be set as the | ||
403 | default for RSA use from then on. | ||
404 | |||
405 | =head2 Advanced configuration support | ||
406 | |||
407 | There is a mechanism supported by the ENGINE framework that allows each | ||
408 | ENGINE implementation to define an arbitrary set of configuration | ||
409 | "commands" and expose them to OpenSSL and any applications based on | ||
410 | OpenSSL. This mechanism is entirely based on the use of name-value pairs | ||
411 | and assumes ASCII input (no unicode or UTF for now!), so it is ideal if | ||
412 | applications want to provide a transparent way for users to provide | ||
413 | arbitrary configuration "directives" directly to such ENGINEs. It is also | ||
414 | possible for the application to dynamically interrogate the loaded ENGINE | ||
415 | implementations for the names, descriptions, and input flags of their | ||
416 | available "control commands", providing a more flexible configuration | ||
417 | scheme. However, if the user is expected to know which ENGINE device he/she | ||
418 | is using (in the case of specialised hardware, this goes without saying) | ||
419 | then applications may not need to concern themselves with discovering the | ||
420 | supported control commands and simply prefer to pass settings into ENGINEs | ||
421 | exactly as they are provided by the user. | ||
422 | |||
423 | Before illustrating how control commands work, it is worth mentioning what | ||
424 | they are typically used for. Broadly speaking there are two uses for | ||
425 | control commands; the first is to provide the necessary details to the | ||
426 | implementation (which may know nothing at all specific to the host system) | ||
427 | so that it can be initialised for use. This could include the path to any | ||
428 | driver or config files it needs to load, required network addresses, | ||
429 | smart-card identifiers, passwords to initialise protected devices, | ||
430 | logging information, etc etc. This class of commands typically needs to be | ||
431 | passed to an ENGINE B<before> attempting to initialise it, ie. before | ||
432 | calling ENGINE_init(). The other class of commands consist of settings or | ||
433 | operations that tweak certain behaviour or cause certain operations to take | ||
434 | place, and these commands may work either before or after ENGINE_init(), or | ||
435 | in some cases both. ENGINE implementations should provide indications of | ||
436 | this in the descriptions attached to builtin control commands and/or in | ||
437 | external product documentation. | ||
438 | |||
439 | I<Issuing control commands to an ENGINE> | ||
440 | |||
441 | Let's illustrate by example; a function for which the caller supplies the | ||
442 | name of the ENGINE it wishes to use, a table of string-pairs for use before | ||
443 | initialisation, and another table for use after initialisation. Note that | ||
444 | the string-pairs used for control commands consist of a command "name" | ||
445 | followed by the command "parameter" - the parameter could be NULL in some | ||
446 | cases but the name can not. This function should initialise the ENGINE | ||
447 | (issuing the "pre" commands beforehand and the "post" commands afterwards) | ||
448 | and set it as the default for everything except RAND and then return a | ||
449 | boolean success or failure. | ||
450 | |||
451 | int | ||
452 | generic_load_engine_fn(const char *engine_id, | ||
453 | const char **pre_cmds, int pre_num, | ||
454 | const char **post_cmds, int post_num) | ||
455 | { | ||
456 | ENGINE *e = ENGINE_by_id(engine_id); | ||
457 | |||
458 | if (!e) | ||
459 | return 0; | ||
460 | while (pre_num--) { | ||
461 | if (!ENGINE_ctrl_cmd_string(e, | ||
462 | pre_cmds[0], pre_cmds[1], 0)) { | ||
463 | fprintf(stderr, | ||
464 | "Failed command (%s - %s:%s)\n", | ||
465 | engine_id, pre_cmds[0], | ||
466 | pre_cmds[1] ? pre_cmds[1] : "(NULL)"); | ||
467 | ENGINE_free(e); | ||
468 | return 0; | ||
469 | } | ||
470 | pre_cmds += 2; | ||
471 | } | ||
472 | if (!ENGINE_init(e)) { | ||
473 | fprintf(stderr, "Failed initialisation\n"); | ||
474 | ENGINE_free(e); | ||
475 | return 0; | ||
476 | } | ||
477 | /* | ||
478 | * ENGINE_init() returned a functional reference, | ||
479 | * so free the structural reference from | ||
480 | * ENGINE_by_id(). | ||
481 | */ | ||
482 | ENGINE_free(e); | ||
483 | while (post_num--) { | ||
484 | if (!ENGINE_ctrl_cmd_string(e, | ||
485 | post_cmds[0], post_cmds[1], 0)) { | ||
486 | fprintf(stderr, | ||
487 | "Failed command (%s - %s:%s)\n", | ||
488 | engine_id, post_cmds[0], | ||
489 | post_cmds[1] ? post_cmds[1] : "(NULL)"); | ||
490 | ENGINE_finish(e); | ||
491 | return 0; | ||
492 | } | ||
493 | post_cmds += 2; | ||
494 | } | ||
495 | ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); | ||
496 | /* Success */ | ||
497 | return 1; | ||
498 | } | ||
499 | |||
500 | Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can | ||
501 | relax the semantics of the function - if set non-zero it will only return | ||
502 | failure if the ENGINE supported the given command name but failed while | ||
503 | executing it, if the ENGINE doesn't support the command name it will simply | ||
504 | return success without doing anything. In this case we assume the user is | ||
505 | only supplying commands specific to the given ENGINE so we set this to | ||
506 | FALSE. | ||
507 | |||
508 | I<Discovering supported control commands> | ||
509 | |||
510 | It is possible to discover at run-time the names, numerical-ids, descriptions | ||
511 | and input parameters of the control commands supported by an ENGINE using a | ||
512 | structural reference. Note that some control commands are defined by OpenSSL | ||
513 | itself and it will intercept and handle these control commands on behalf of the | ||
514 | ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. | ||
515 | openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands | ||
516 | implemented by ENGINEs should be numbered from. Any command value lower than | ||
517 | this symbol is considered a "generic" command is handled directly by the | ||
518 | OpenSSL core routines. | ||
519 | |||
520 | It is using these "core" control commands that one can discover the control | ||
521 | commands implemented by a given ENGINE, specifically the commands; | ||
522 | |||
523 | #define ENGINE_HAS_CTRL_FUNCTION 10 | ||
524 | #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 | ||
525 | #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 | ||
526 | #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 | ||
527 | #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 | ||
528 | #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 | ||
529 | #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 | ||
530 | #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 | ||
531 | #define ENGINE_CTRL_GET_CMD_FLAGS 18 | ||
532 | |||
533 | Whilst these commands are automatically processed by the OpenSSL framework code, | ||
534 | they use various properties exposed by each ENGINE to process these | ||
535 | queries. An ENGINE has 3 properties it exposes that can affect how this behaves; | ||
536 | it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in | ||
537 | the ENGINE's flags, and it can expose an array of control command descriptions. | ||
538 | If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will | ||
539 | simply pass all these "core" control commands directly to the ENGINE's ctrl() | ||
540 | handler (and thus, it must have supplied one), so it is up to the ENGINE to | ||
541 | reply to these "discovery" commands itself. If that flag is not set, then the | ||
542 | OpenSSL framework code will work with the following rules; | ||
543 | |||
544 | if no ctrl() handler supplied; | ||
545 | ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), | ||
546 | all other commands fail. | ||
547 | if a ctrl() handler was supplied but no array of control commands; | ||
548 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | ||
549 | all other commands fail. | ||
550 | if a ctrl() handler and array of control commands was supplied; | ||
551 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | ||
552 | all other commands proceed processing ... | ||
553 | |||
554 | If the ENGINE's array of control commands is empty then all other commands will | ||
555 | fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of | ||
556 | the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the | ||
557 | identifier of a command supported by the ENGINE and returns the next command | ||
558 | identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string | ||
559 | name for a command and returns the corresponding identifier or fails if no such | ||
560 | command name exists, and the remaining commands take a command identifier and | ||
561 | return properties of the corresponding commands. All except | ||
562 | ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, | ||
563 | or populate a supplied character buffer with a copy of the command name or | ||
564 | description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following | ||
565 | possible values; | ||
566 | |||
567 | #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 | ||
568 | #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 | ||
569 | #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 | ||
570 | #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 | ||
571 | |||
572 | If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely | ||
573 | informational to the caller - this flag will prevent the command being usable | ||
574 | for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). | ||
575 | "INTERNAL" commands are not intended to be exposed to text-based configuration | ||
576 | by applications, administrations, users, etc. These can support arbitrary | ||
577 | operations via ENGINE_ctrl(), including passing to and/or from the control | ||
578 | commands data of any arbitrary type. These commands are supported in the | ||
579 | discovery mechanisms simply allow applications to determine if an ENGINE | ||
580 | supports certain specific commands it might want to use (eg. application "foo" | ||
581 | might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - | ||
582 | and ENGINE could therefore decide whether or not to support this "foo"-specific | ||
583 | extension). | ||
584 | |||
585 | =head2 Future developments | ||
586 | |||
587 | The ENGINE API and internal architecture is currently being reviewed. Slated for | ||
588 | possible release in 0.9.8 is support for transparent loading of "dynamic" | ||
589 | ENGINEs (built as self-contained shared-libraries). This would allow ENGINE | ||
590 | implementations to be provided independently of OpenSSL libraries and/or | ||
591 | OpenSSL-based applications, and would also remove any requirement for | ||
592 | applications to explicitly use the "dynamic" ENGINE to bind to shared-library | ||
593 | implementations. | ||
594 | |||
595 | =head1 SEE ALSO | ||
596 | |||
597 | L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> | ||
598 | |||
599 | =cut | ||
diff --git a/src/lib/libcrypto/doc/lh_stats.pod b/src/lib/libcrypto/doc/lh_stats.pod deleted file mode 100644 index 15f97b5545..0000000000 --- a/src/lib/libcrypto/doc/lh_stats.pod +++ /dev/null | |||
@@ -1,60 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, | ||
6 | lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/lhash.h> | ||
11 | |||
12 | void lh_stats(LHASH *table, FILE *out); | ||
13 | void lh_node_stats(LHASH *table, FILE *out); | ||
14 | void lh_node_usage_stats(LHASH *table, FILE *out); | ||
15 | |||
16 | void lh_stats_bio(LHASH *table, BIO *out); | ||
17 | void lh_node_stats_bio(LHASH *table, BIO *out); | ||
18 | void lh_node_usage_stats_bio(LHASH *table, BIO *out); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | The B<LHASH> structure records statistics about most aspects of | ||
23 | accessing the hash table. This is mostly a legacy of Eric Young | ||
24 | writing this library for the reasons of implementing what looked like | ||
25 | a nice algorithm rather than for a particular software product. | ||
26 | |||
27 | lh_stats() prints out statistics on the size of the hash table, how | ||
28 | many entries are in it, and the number and result of calls to the | ||
29 | routines in this library. | ||
30 | |||
31 | lh_node_stats() prints the number of entries for each 'bucket' in the | ||
32 | hash table. | ||
33 | |||
34 | lh_node_usage_stats() prints out a short summary of the state of the | ||
35 | hash table. It prints the 'load' and the 'actual load'. The load is | ||
36 | the average number of data items per 'bucket' in the hash table. The | ||
37 | 'actual load' is the average number of items per 'bucket', but only | ||
38 | for buckets which contain entries. So the 'actual load' is the | ||
39 | average number of searches that will need to find an item in the hash | ||
40 | table, while the 'load' is the average number that will be done to | ||
41 | record a miss. | ||
42 | |||
43 | lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() | ||
44 | are the same as the above, except that the output goes to a B<BIO>. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | These functions do not return values. | ||
49 | |||
50 | =head1 SEE ALSO | ||
51 | |||
52 | L<bio(3)|bio(3)>, L<lh_new(3)|lh_new(3)> | ||
53 | |||
54 | =head1 HISTORY | ||
55 | |||
56 | These functions are available in all versions of SSLeay and OpenSSL. | ||
57 | |||
58 | This manpage is derived from the SSLeay documentation. | ||
59 | |||
60 | =cut | ||