diff options
author | beck <> | 2000-03-19 11:13:58 +0000 |
---|---|---|
committer | beck <> | 2000-03-19 11:13:58 +0000 |
commit | 796d609550df3a33fc11468741c5d2f6d3df4c11 (patch) | |
tree | 6c6d539061caa20372dad0ac4ddb1dfae2fbe7fe /src/lib/libcrypto/doc | |
parent | 5be3114c1fd7e0dfea1e38d3abb4cbba75244419 (diff) | |
download | openbsd-796d609550df3a33fc11468741c5d2f6d3df4c11.tar.gz openbsd-796d609550df3a33fc11468741c5d2f6d3df4c11.tar.bz2 openbsd-796d609550df3a33fc11468741c5d2f6d3df4c11.zip |
OpenSSL 0.9.5 merge
*warning* this bumps shared lib minors for libssl and libcrypto from 2.1 to 2.2
if you are using the ssl26 packages for ssh and other things to work you will
need to get new ones (see ~beck/libsslsnap/<arch>) on cvs or ~beck/src-patent.tar.gz on cvs
Diffstat (limited to 'src/lib/libcrypto/doc')
54 files changed, 3606 insertions, 0 deletions
diff --git a/src/lib/libcrypto/doc/DH_generate_key.pod b/src/lib/libcrypto/doc/DH_generate_key.pod new file mode 100644 index 0000000000..920995b2e5 --- /dev/null +++ b/src/lib/libcrypto/doc/DH_generate_key.pod | |||
@@ -0,0 +1,50 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | int DH_generate_key(DH *dh); | ||
12 | |||
13 | int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DH_generate_key() performs the first step of a Diffie-Hellman key | ||
18 | exchange by generating private and public DH values. By calling | ||
19 | DH_compute_key(), these are combined with the other party's public | ||
20 | value to compute the shared key. | ||
21 | |||
22 | DH_generate_key() expects B<dh> to contain the shared parameters | ||
23 | B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value | ||
24 | unless B<dh-E<gt>priv_key> is already set, and computes the | ||
25 | corresponding public value B<dh-E<gt>pub_key>, which can then be | ||
26 | published. | ||
27 | |||
28 | DH_compute_key() computes the shared secret from the private DH value | ||
29 | in B<dh> and the other party's public value in B<pub_key> and stores | ||
30 | it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | DH_generate_key() returns 1 on success, 0 otherwise. | ||
35 | |||
36 | DH_compute_key() returns the size of the shared secret on success, -1 | ||
37 | on error. | ||
38 | |||
39 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
40 | |||
41 | =head1 SEE ALSO | ||
42 | |||
43 | L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> | ||
44 | |||
45 | =head1 HISTORY | ||
46 | |||
47 | DH_generate_key() and DH_compute_key() are available in all versions | ||
48 | of SSLeay and OpenSSL. | ||
49 | |||
50 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_generate_parameters.pod b/src/lib/libcrypto/doc/DH_generate_parameters.pod new file mode 100644 index 0000000000..a7d0c75f0c --- /dev/null +++ b/src/lib/libcrypto/doc/DH_generate_parameters.pod | |||
@@ -0,0 +1,72 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH *DH_generate_parameters(int prime_len, int generator, | ||
12 | void (*callback)(int, int, void *), void *cb_arg); | ||
13 | |||
14 | int DH_check(DH *dh, int *codes); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | DH_generate_parameters() generates Diffie-Hellman parameters that can | ||
19 | be shared among a group of users, and returns them in a newly | ||
20 | allocated B<DH> structure. The pseudo-random number generator must be | ||
21 | seeded prior to calling DH_generate_parameters(). | ||
22 | |||
23 | B<prime_len> is the length in bits of the safe prime to be generated. | ||
24 | B<generator> is a small number E<gt> 1, typically 2 or 5. | ||
25 | |||
26 | A callback function may be used to provide feedback about the progress | ||
27 | of the key generation. If B<callback> is not B<NULL>, it will be | ||
28 | called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime | ||
29 | number is generated, and when a prime has been found, B<callback(3, | ||
30 | 0, cb_arg)> is called. | ||
31 | |||
32 | DH_check() validates Diffie-Hellman parameters. It checks that B<p> is | ||
33 | a safe prime, and that B<g> is a suitable generator. In the case of an | ||
34 | error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or | ||
35 | DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. | ||
36 | DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be | ||
37 | checked, i.e. it does not equal 2 or 5. | ||
38 | |||
39 | =head1 RETURN VALUES | ||
40 | |||
41 | DH_generate_parameters() returns a pointer to the DH structure, or | ||
42 | NULL if the parameter generation fails. The error codes can be | ||
43 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
44 | |||
45 | DH_check() returns 1 if the check could be performed, 0 otherwise. | ||
46 | |||
47 | =head1 NOTES | ||
48 | |||
49 | DH_generate_parameters() may run for several hours before finding a | ||
50 | suitable prime. | ||
51 | |||
52 | The parameters generated by DH_generate_parameters() are not to be | ||
53 | used in signature schemes. | ||
54 | |||
55 | =head1 BUGS | ||
56 | |||
57 | If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not | ||
58 | a usable generator. | ||
59 | |||
60 | =head1 SEE ALSO | ||
61 | |||
62 | L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_free(3)|DH_free(3)> | ||
63 | |||
64 | =head1 HISTORY | ||
65 | |||
66 | DH_check() is available in all versions of SSLeay and OpenSSL. | ||
67 | The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. | ||
68 | |||
69 | In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used | ||
70 | instead of DH_CHECK_P_NOT_SAFE_PRIME. | ||
71 | |||
72 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_get_ex_new_index.pod b/src/lib/libcrypto/doc/DH_get_ex_new_index.pod new file mode 100644 index 0000000000..82e2548bcd --- /dev/null +++ b/src/lib/libcrypto/doc/DH_get_ex_new_index.pod | |||
@@ -0,0 +1,36 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | int DH_get_ex_new_index(long argl, void *argp, | ||
12 | CRYPTO_EX_new *new_func, | ||
13 | CRYPTO_EX_dup *dup_func, | ||
14 | CRYPTO_EX_free *free_func); | ||
15 | |||
16 | int DH_set_ex_data(DH *d, int idx, void *arg); | ||
17 | |||
18 | char *DH_get_ex_data(DH *d, int idx); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | These functions handle application specific data in DH | ||
23 | structures. Their usage is identical to that of | ||
24 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() | ||
25 | as described in L<RSA_get_ex_new_index(3)>. | ||
26 | |||
27 | =head1 SEE ALSO | ||
28 | |||
29 | L<RSA_get_ex_new_index()|RSA_get_ex_new_index()>, L<dh(3)|dh(3)> | ||
30 | |||
31 | =head1 HISTORY | ||
32 | |||
33 | DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are | ||
34 | available since OpenSSL 0.9.5. | ||
35 | |||
36 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_new.pod b/src/lib/libcrypto/doc/DH_new.pod new file mode 100644 index 0000000000..64624b9d15 --- /dev/null +++ b/src/lib/libcrypto/doc/DH_new.pod | |||
@@ -0,0 +1,40 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_new, DH_free - allocate and free DH objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH* DH_new(void); | ||
12 | |||
13 | void DH_free(DH *dh); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DH_new() allocates and initializes a B<DH> structure. | ||
18 | |||
19 | DH_free() frees the B<DH> structure and its components. The values are | ||
20 | erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, DH_new() returns B<NULL> and sets an error | ||
25 | code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns | ||
26 | a pointer to the newly allocated structure. | ||
27 | |||
28 | DH_free() returns no value. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<dh(3)|dh(3)>, L<err(3)|err(3)>, | ||
33 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>, | ||
34 | L<DH_generate_key(3)|DH_generate_key(3)> | ||
35 | |||
36 | =head1 HISTORY | ||
37 | |||
38 | DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. | ||
39 | |||
40 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_set_method.pod b/src/lib/libcrypto/doc/DH_set_method.pod new file mode 100644 index 0000000000..dca41d8dbc --- /dev/null +++ b/src/lib/libcrypto/doc/DH_set_method.pod | |||
@@ -0,0 +1,99 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_set_default_method, DH_get_default_method, DH_set_method, | ||
6 | DH_new_method, DH_OpenSSL - select DH method | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/dh.h> | ||
11 | |||
12 | void DH_set_default_method(DH_METHOD *meth); | ||
13 | |||
14 | DH_METHOD *DH_get_default_method(void); | ||
15 | |||
16 | DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); | ||
17 | |||
18 | DH *DH_new_method(DH_METHOD *meth); | ||
19 | |||
20 | DH_METHOD *DH_OpenSSL(void); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman | ||
25 | operations. By modifying the method, alternative implementations | ||
26 | such as hardware accelerators may be used. | ||
27 | |||
28 | Initially, the default is to use the OpenSSL internal implementation. | ||
29 | DH_OpenSSL() returns a pointer to that method. | ||
30 | |||
31 | DH_set_default_method() makes B<meth> the default method for all B<DH> | ||
32 | structures created later. | ||
33 | |||
34 | DH_get_default_method() returns a pointer to the current default | ||
35 | method. | ||
36 | |||
37 | DH_set_method() selects B<meth> for all operations using the structure B<dh>. | ||
38 | |||
39 | DH_get_method() returns a pointer to the method currently selected | ||
40 | for B<dh>. | ||
41 | |||
42 | DH_new_method() allocates and initializes a B<DH> structure so that | ||
43 | B<method> will be used for the DH operations. If B<method> is B<NULL>, | ||
44 | the default method is used. | ||
45 | |||
46 | =head1 THE DH_METHOD STRUCTURE | ||
47 | |||
48 | typedef struct dh_meth_st | ||
49 | { | ||
50 | /* name of the implementation */ | ||
51 | const char *name; | ||
52 | |||
53 | /* generate private and public DH values for key agreement */ | ||
54 | int (*generate_key)(DH *dh); | ||
55 | |||
56 | /* compute shared secret */ | ||
57 | int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
58 | |||
59 | /* compute r = a ^ p mod m. May be NULL */ | ||
60 | int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
61 | const BIGNUM *m, BN_CTX *ctx, | ||
62 | BN_MONT_CTX *m_ctx); | ||
63 | |||
64 | /* called at DH_new */ | ||
65 | int (*init)(DH *dh); | ||
66 | |||
67 | /* called at DH_free */ | ||
68 | int (*finish)(DH *dh); | ||
69 | |||
70 | int flags; | ||
71 | |||
72 | char *app_data; /* ?? */ | ||
73 | |||
74 | } DH_METHOD; | ||
75 | |||
76 | =head1 RETURN VALUES | ||
77 | |||
78 | DH_OpenSSL(), DH_get_default_method() and DH_get_method() return | ||
79 | pointers to the respective B<DH_METHOD>s. | ||
80 | |||
81 | DH_set_default_method() returns no value. | ||
82 | |||
83 | DH_set_method() returns a pointer to the B<DH_METHOD> previously | ||
84 | associated with B<dh>. | ||
85 | |||
86 | DH_new_method() returns B<NULL> and sets an error code that can be | ||
87 | obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it | ||
88 | returns a pointer to the newly allocated structure. | ||
89 | |||
90 | =head1 SEE ALSO | ||
91 | |||
92 | L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> | ||
93 | |||
94 | =head1 HISTORY | ||
95 | |||
96 | DH_set_default_method(), DH_get_default_method(), DH_set_method(), | ||
97 | DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. | ||
98 | |||
99 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_size.pod b/src/lib/libcrypto/doc/DH_size.pod new file mode 100644 index 0000000000..97f26fda78 --- /dev/null +++ b/src/lib/libcrypto/doc/DH_size.pod | |||
@@ -0,0 +1,33 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_size - get Diffie-Hellman prime size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | int DH_size(DH *dh); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the Diffie-Hellman size in bytes. It can be used | ||
16 | to determine how much memory must be allocated for the shared secret | ||
17 | computed by DH_compute_key(). | ||
18 | |||
19 | B<dh-E<gt>p> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | DH_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_SIG_new.pod b/src/lib/libcrypto/doc/DSA_SIG_new.pod new file mode 100644 index 0000000000..671655554a --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_SIG_new.pod | |||
@@ -0,0 +1,39 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA_SIG *DSA_SIG_new(void); | ||
12 | |||
13 | void DSA_SIG_free(DSA_SIG *a); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure. | ||
18 | |||
19 | DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The | ||
20 | values are erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an | ||
25 | error code that can be obtained by | ||
26 | L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer | ||
27 | to the newly allocated structure. | ||
28 | |||
29 | DSA_SIG_free() returns no value. | ||
30 | |||
31 | =head1 SEE ALSO | ||
32 | |||
33 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_do_sign(3)|DSA_do_sign(3)> | ||
34 | |||
35 | =head1 HISTORY | ||
36 | |||
37 | DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. | ||
38 | |||
39 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_do_sign.pod b/src/lib/libcrypto/doc/DSA_do_sign.pod new file mode 100644 index 0000000000..a24fd5714e --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_do_sign.pod | |||
@@ -0,0 +1,47 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_do_sign, DSA_do_verify - raw DSA signature operations | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); | ||
12 | |||
13 | int DSA_do_verify(const unsigned char *dgst, int dgst_len, | ||
14 | DSA_SIG *sig, DSA *dsa); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | DSA_do_sign() computes a digital signature on the B<len> byte message | ||
19 | digest B<dgst> using the private key B<dsa> and returns it in a | ||
20 | newly allocated B<DSA_SIG> structure. | ||
21 | |||
22 | L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part | ||
23 | of the signing operation in case signature generation is | ||
24 | time-critical. | ||
25 | |||
26 | DSA_do_verify() verifies that the signature B<sig> matches a given | ||
27 | message digest B<dgst> of size B<len>. B<dsa> is the signer's public | ||
28 | key. | ||
29 | |||
30 | =head1 RETURN VALUES | ||
31 | |||
32 | DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() | ||
33 | returns 1 for a valid signature, 0 for an incorrect signature and -1 | ||
34 | on error. The error codes can be obtained by | ||
35 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
36 | |||
37 | =head1 SEE ALSO | ||
38 | |||
39 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
40 | L<DSA_SIG_new(3)|DSA_SIG_new(3)>, | ||
41 | L<DSA_sign(3)|DSA_sign(3)> | ||
42 | |||
43 | =head1 HISTORY | ||
44 | |||
45 | DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. | ||
46 | |||
47 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod new file mode 100644 index 0000000000..29cb1075d1 --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_dup_DH.pod | |||
@@ -0,0 +1,36 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_dup_DH - create a DH structure out of DSA structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DH * DSA_dup_DH(DSA *r); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q | ||
16 | is lost during that conversion, but the resulting DH parameters | ||
17 | contain its length. | ||
18 | |||
19 | =head1 RETURN VALUE | ||
20 | |||
21 | DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The | ||
22 | error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
23 | |||
24 | =head1 NOTE | ||
25 | |||
26 | Be careful to avoid small subgroup attacks when using this. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)> | ||
31 | |||
32 | =head1 HISTORY | ||
33 | |||
34 | DSA_dup_DH() was added in OpenSSL 0.9.4. | ||
35 | |||
36 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_generate_key.pod b/src/lib/libcrypto/doc/DSA_generate_key.pod new file mode 100644 index 0000000000..52890db5be --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_generate_key.pod | |||
@@ -0,0 +1,33 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_generate_key - generate DSA key pair | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_generate_key(DSA *a); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | DSA_generate_key() expects B<a> to contain DSA parameters. It generates | ||
16 | a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>. | ||
17 | |||
18 | The PRNG must be seeded prior to calling DSA_generate_key(). | ||
19 | |||
20 | =head1 RETURN VALUE | ||
21 | |||
22 | DSA_generate_key() returns 1 on success, 0 otherwise. | ||
23 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | DSA_generate_key() is available since SSLeay 0.8. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_generate_parameters.pod b/src/lib/libcrypto/doc/DSA_generate_parameters.pod new file mode 100644 index 0000000000..43f60b0eb9 --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_generate_parameters.pod | |||
@@ -0,0 +1,105 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_generate_parameters - generate DSA parameters | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA *DSA_generate_parameters(int bits, unsigned char *seed, | ||
12 | int seed_len, int *counter_ret, unsigned long *h_ret, | ||
13 | void (*callback)(int, int, void *), void *cb_arg); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DSA_generate_parameters() generates primes p and q and a generator g | ||
18 | for use in the DSA. | ||
19 | |||
20 | B<bits> is the length of the prime to be generated; the DSS allows a | ||
21 | maximum of 1024 bits. | ||
22 | |||
23 | If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be | ||
24 | generated at random. Otherwise, the seed is used to generate | ||
25 | them. If the given seed does not yield a prime q, a new random | ||
26 | seed is chosen and placed at B<seed>. | ||
27 | |||
28 | DSA_generate_parameters() places the iteration count in | ||
29 | *B<counter_ret> and a counter used for finding a generator in | ||
30 | *B<h_ret>, unless these are B<NULL>. | ||
31 | |||
32 | A callback function may be used to provide feedback about the progress | ||
33 | of the key generation. If B<callback> is not B<NULL>, it will be | ||
34 | called as follows: | ||
35 | |||
36 | =over 4 | ||
37 | |||
38 | =item * | ||
39 | |||
40 | When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called | ||
41 | (m is 0 for the first candidate). | ||
42 | |||
43 | =item * | ||
44 | |||
45 | When a candidate for q has passed a test by trial division, | ||
46 | B<callback(1, -1, cb_arg)> is called. | ||
47 | While a candidate for q is tested by Miller-Rabin primality tests, | ||
48 | B<callback(1, i, cb_arg)> is called in the outer loop | ||
49 | (once for each witness that confirms that the candidate may be prime); | ||
50 | i is the loop counter (starting at 0). | ||
51 | |||
52 | =item * | ||
53 | |||
54 | When a prime q has been found, B<callback(2, 0, cb_arg)> and | ||
55 | B<callback(3, 0, cb_arg)> are called. | ||
56 | |||
57 | =item * | ||
58 | |||
59 | Before a candidate for p (other than the first) is generated and tested, | ||
60 | B<callback(0, counter, cb_arg)> is called. | ||
61 | |||
62 | =item * | ||
63 | |||
64 | When a candidate for p has passed the test by trial division, | ||
65 | B<callback(1, -1, cb_arg)> is called. | ||
66 | While it is tested by the Miller-Rabin primality test, | ||
67 | B<callback(1, i, cb_arg)> is called in the outer loop | ||
68 | (once for each witness that confirms that the candidate may be prime). | ||
69 | i is the loop counter (starting at 0). | ||
70 | |||
71 | =item * | ||
72 | |||
73 | When p has been found, B<callback(2, 1, cb_arg)> is called. | ||
74 | |||
75 | =item * | ||
76 | |||
77 | When the generator has been found, B<callback(3, 1, cb_arg)> is called. | ||
78 | |||
79 | =back | ||
80 | |||
81 | =head1 RETURN VALUE | ||
82 | |||
83 | DSA_generate_parameters() returns a pointer to the DSA structure, or | ||
84 | B<NULL> if the parameter generation fails. The error codes can be | ||
85 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
86 | |||
87 | =head1 BUGS | ||
88 | |||
89 | Seed lengths E<gt> 20 are not supported. | ||
90 | |||
91 | =head1 SEE ALSO | ||
92 | |||
93 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
94 | L<DSA_free(3)|DSA_free(3)> | ||
95 | |||
96 | =head1 HISTORY | ||
97 | |||
98 | DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> | ||
99 | argument was added in SSLeay 0.9.0. | ||
100 | In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called | ||
101 | in the inner loop of the Miller-Rabin test whenever it reached the | ||
102 | squaring step (the parameters to B<callback> did not reveal how many | ||
103 | witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> | ||
104 | is called as in BN_is_prime(3), i.e. once for each witness. | ||
105 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod new file mode 100644 index 0000000000..4612e708ec --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod | |||
@@ -0,0 +1,36 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/DSA.h> | ||
10 | |||
11 | int DSA_get_ex_new_index(long argl, void *argp, | ||
12 | CRYPTO_EX_new *new_func, | ||
13 | CRYPTO_EX_dup *dup_func, | ||
14 | CRYPTO_EX_free *free_func); | ||
15 | |||
16 | int DSA_set_ex_data(DSA *d, int idx, void *arg); | ||
17 | |||
18 | char *DSA_get_ex_data(DSA *d, int idx); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | These functions handle application specific data in DSA | ||
23 | structures. Their usage is identical to that of | ||
24 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() | ||
25 | as described in L<RSA_get_ex_new_index(3)>. | ||
26 | |||
27 | =head1 SEE ALSO | ||
28 | |||
29 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> | ||
30 | |||
31 | =head1 HISTORY | ||
32 | |||
33 | DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are | ||
34 | available since OpenSSL 0.9.5. | ||
35 | |||
36 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod new file mode 100644 index 0000000000..7dde54445b --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_new.pod | |||
@@ -0,0 +1,41 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_new, DSA_free - allocate and free DSA objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA* DSA_new(void); | ||
12 | |||
13 | void DSA_free(DSA *dsa); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DSA_new() allocates and initializes a B<DSA> structure. | ||
18 | |||
19 | DSA_free() frees the B<DSA> structure and its components. The values are | ||
20 | erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, DSA_new() returns B<NULL> and sets an error | ||
25 | code that can be obtained by | ||
26 | L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer | ||
27 | to the newly allocated structure. | ||
28 | |||
29 | DSA_free() returns no value. | ||
30 | |||
31 | =head1 SEE ALSO | ||
32 | |||
33 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, | ||
34 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, | ||
35 | L<DSA_generate_key(3)|DSA_generate_key(3)> | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. | ||
40 | |||
41 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod new file mode 100644 index 0000000000..0b13ec9237 --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_set_method.pod | |||
@@ -0,0 +1,111 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_set_default_method, DSA_get_default_method, DSA_set_method, | ||
6 | DSA_new_method, DSA_OpenSSL - select RSA method | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/DSA.h> | ||
11 | |||
12 | void DSA_set_default_method(DSA_METHOD *meth); | ||
13 | |||
14 | DSA_METHOD *DSA_get_default_method(void); | ||
15 | |||
16 | DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); | ||
17 | |||
18 | DSA *DSA_new_method(DSA_METHOD *meth); | ||
19 | |||
20 | DSA_METHOD *DSA_OpenSSL(void); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA | ||
25 | operations. By modifying the method, alternative implementations | ||
26 | such as hardware accelerators may be used. | ||
27 | |||
28 | Initially, the default is to use the OpenSSL internal implementation. | ||
29 | DSA_OpenSSL() returns a pointer to that method. | ||
30 | |||
31 | DSA_set_default_method() makes B<meth> the default method for all B<DSA> | ||
32 | structures created later. | ||
33 | |||
34 | DSA_get_default_method() returns a pointer to the current default | ||
35 | method. | ||
36 | |||
37 | DSA_set_method() selects B<meth> for all operations using the structure B<DSA>. | ||
38 | |||
39 | DSA_get_method() returns a pointer to the method currently selected | ||
40 | for B<DSA>. | ||
41 | |||
42 | DSA_new_method() allocates and initializes a B<DSA> structure so that | ||
43 | B<method> will be used for the DSA operations. If B<method> is B<NULL>, | ||
44 | the default method is used. | ||
45 | |||
46 | =head1 THE DSA_METHOD STRUCTURE | ||
47 | |||
48 | struct | ||
49 | { | ||
50 | /* name of the implementation */ | ||
51 | const char *name; | ||
52 | |||
53 | /* sign */ | ||
54 | DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, | ||
55 | DSA *dsa); | ||
56 | |||
57 | /* pre-compute k^-1 and r */ | ||
58 | int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, | ||
59 | BIGNUM **rp); | ||
60 | |||
61 | /* verify */ | ||
62 | int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, | ||
63 | DSA_SIG *sig, DSA *dsa); | ||
64 | |||
65 | /* compute rr = a1^p1 * a2^p2 mod m. May be NULL */ | ||
66 | int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, | ||
67 | BIGNUM *a2, BIGNUM *p2, BIGNUM *m, | ||
68 | BN_CTX *ctx, BN_MONT_CTX *in_mont); | ||
69 | |||
70 | /* compute r = a ^ p mod m. May be NULL */ | ||
71 | int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, | ||
72 | const BIGNUM *p, const BIGNUM *m, | ||
73 | BN_CTX *ctx, BN_MONT_CTX *m_ctx); | ||
74 | |||
75 | /* called at DSA_new */ | ||
76 | int (*init)(DSA *DSA); | ||
77 | |||
78 | /* called at DSA_free */ | ||
79 | int (*finish)(DSA *DSA); | ||
80 | |||
81 | int flags; | ||
82 | |||
83 | char *app_data; /* ?? */ | ||
84 | |||
85 | } DSA_METHOD; | ||
86 | |||
87 | =head1 RETURN VALUES | ||
88 | |||
89 | DSA_OpenSSL(), DSA_get_default_method() and DSA_get_method() return | ||
90 | pointers to the respective B<DSA_METHOD>s. | ||
91 | |||
92 | DSA_set_default_method() returns no value. | ||
93 | |||
94 | DSA_set_method() returns a pointer to the B<DSA_METHOD> previously | ||
95 | associated with B<dsa>. | ||
96 | |||
97 | DSA_new_method() returns B<NULL> and sets an error code that can be | ||
98 | obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation | ||
99 | fails. Otherwise it returns a pointer to the newly allocated | ||
100 | structure. | ||
101 | |||
102 | =head1 SEE ALSO | ||
103 | |||
104 | L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> | ||
105 | |||
106 | =head1 HISTORY | ||
107 | |||
108 | DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), | ||
109 | DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. | ||
110 | |||
111 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_sign.pod b/src/lib/libcrypto/doc/DSA_sign.pod new file mode 100644 index 0000000000..f6e60a8ca3 --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_sign.pod | |||
@@ -0,0 +1,66 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_sign(int type, const unsigned char *dgst, int len, | ||
12 | unsigned char *sigret, unsigned int *siglen, DSA *dsa); | ||
13 | |||
14 | int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, | ||
15 | BIGNUM **rp); | ||
16 | |||
17 | int DSA_verify(int type, const unsigned char *dgst, int len, | ||
18 | unsigned char *sigbuf, int siglen, DSA *dsa); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | DSA_sign() computes a digital signature on the B<len> byte message | ||
23 | digest B<dgst> using the private key B<dsa> and places its ASN.1 DER | ||
24 | encoding at B<sigret>. The length of the signature is places in | ||
25 | *B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory. | ||
26 | |||
27 | DSA_sign_setup() may be used to precompute part of the signing | ||
28 | operation in case signature generation is time-critical. It expects | ||
29 | B<dsa> to contain DSA parameters. It places the precomputed values | ||
30 | in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing | ||
31 | the old ones unless *B<kinvp> and *B<rp> are NULL. These values may | ||
32 | be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. | ||
33 | B<ctx> is a pre-allocated B<BN_CTX> or NULL. | ||
34 | |||
35 | DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> | ||
36 | matches a given message digest B<dgst> of size B<len>. | ||
37 | B<dsa> is the signer's public key. | ||
38 | |||
39 | The B<type> parameter is ignored. | ||
40 | |||
41 | The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) | ||
42 | is called. | ||
43 | |||
44 | =head1 RETURN VALUES | ||
45 | |||
46 | DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. | ||
47 | DSA_verify() returns 1 for a valid signature, 0 for an incorrect | ||
48 | signature and -1 on error. The error codes can be obtained by | ||
49 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
50 | |||
51 | =head1 CONFORMING TO | ||
52 | |||
53 | US Federal Information Processing Standard FIPS 186 (Digital Signature | ||
54 | Standard, DSS), ANSI X9.30 | ||
55 | |||
56 | =head1 SEE ALSO | ||
57 | |||
58 | L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
59 | L<DSA_do_sign(3)|DSA_do_sign(3)> | ||
60 | |||
61 | =head1 HISTORY | ||
62 | |||
63 | DSA_sign() and DSA_verify() are available in all versions of SSLeay. | ||
64 | DSA_sign_setup() was added in SSLeay 0.8. | ||
65 | |||
66 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod new file mode 100644 index 0000000000..23b6320a4d --- /dev/null +++ b/src/lib/libcrypto/doc/DSA_size.pod | |||
@@ -0,0 +1,33 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_size - get DSA signature size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_size(DSA *dsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the size of an ASN.1 encoded DSA signature in | ||
16 | bytes. It can be used to determine how much memory must be allocated | ||
17 | for a DSA signature. | ||
18 | |||
19 | B<dsa-E<gt>q> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | DSA_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_GET_LIB.pod b/src/lib/libcrypto/doc/ERR_GET_LIB.pod new file mode 100644 index 0000000000..2a129da036 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_GET_LIB.pod | |||
@@ -0,0 +1,51 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and | ||
6 | reason code | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | int ERR_GET_LIB(unsigned long e); | ||
13 | |||
14 | int ERR_GET_FUNC(unsigned long e); | ||
15 | |||
16 | int ERR_GET_REASON(unsigned long e); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | The error code returned by ERR_get_error() consists of a library | ||
21 | number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() | ||
22 | and ERR_GET_REASON() can be used to extract these. | ||
23 | |||
24 | The library number and function code describe where the error | ||
25 | occurred, the reason code is the information about what went wrong. | ||
26 | |||
27 | Each sub-library of OpenSSL has a unique library number; function and | ||
28 | reason codes are unique within each sub-library. Note that different | ||
29 | libraries may use the same value to signal different functions and | ||
30 | reasons. | ||
31 | |||
32 | B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally | ||
33 | unique. However, when checking for sub-library specific reason codes, | ||
34 | be sure to also compare the library number. | ||
35 | |||
36 | ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | The library number, function code and reason code respectively. | ||
41 | |||
42 | =head1 SEE ALSO | ||
43 | |||
44 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
45 | |||
46 | =head1 HISTORY | ||
47 | |||
48 | ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in | ||
49 | all versions of SSLeay and OpenSSL. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_clear_error.pod b/src/lib/libcrypto/doc/ERR_clear_error.pod new file mode 100644 index 0000000000..566e1f4e31 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_clear_error.pod | |||
@@ -0,0 +1,29 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_clear_error - clear the error queue | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_clear_error(void); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | ERR_clear_error() empties the current thread's error queue. | ||
16 | |||
17 | =head1 RETURN VALUES | ||
18 | |||
19 | ERR_clear_error() has no return value. | ||
20 | |||
21 | =head1 SEE ALSO | ||
22 | |||
23 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
24 | |||
25 | =head1 HISTORY | ||
26 | |||
27 | ERR_clear_error() is available in all versions of SSLeay and OpenSSL. | ||
28 | |||
29 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_error_string.pod b/src/lib/libcrypto/doc/ERR_error_string.pod new file mode 100644 index 0000000000..0d2417599c --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_error_string.pod | |||
@@ -0,0 +1,65 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_error_string - obtain human-readable error message | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | char *ERR_error_string(unsigned long e, char *buf); | ||
12 | |||
13 | const char *ERR_lib_error_string(unsigned long e); | ||
14 | const char *ERR_func_error_string(unsigned long e); | ||
15 | const char *ERR_reason_error_string(unsigned long e); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | ERR_error_string() generates a human-readable string representing the | ||
20 | error code B<e>, and places it at B<buf>. B<buf> must be at least 120 | ||
21 | bytes long. If B<buf> is B<NULL>, the error string is placed in a | ||
22 | static buffer. | ||
23 | |||
24 | The string will have the following format: | ||
25 | |||
26 | error:[error code]:[library name]:[function name]:[reason string] | ||
27 | |||
28 | I<error code> is an 8 digit hexadecimal number, I<library name>, | ||
29 | I<function name> and I<reason string> are ASCII text. | ||
30 | |||
31 | ERR_lib_error_string(), ERR_func_error_string() and | ||
32 | ERR_reason_error_string() return the library name, function | ||
33 | name and reason string respectively. | ||
34 | |||
35 | The OpenSSL error strings should be loaded by calling | ||
36 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL | ||
37 | applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
38 | first. | ||
39 | If there is no text string registered for the given error code, | ||
40 | the error string will contain the numeric code. | ||
41 | |||
42 | L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print | ||
43 | all error codes currently in the queue. | ||
44 | |||
45 | =head1 RETURN VALUES | ||
46 | |||
47 | ERR_error_string() returns a pointer to a static buffer containing the | ||
48 | string if B<buf == NULL>, B<buf> otherwise. | ||
49 | |||
50 | ERR_lib_error_string(), ERR_func_error_string() and | ||
51 | ERR_reason_error_string() return the strings, and B<NULL> if | ||
52 | none is registered for the error code. | ||
53 | |||
54 | =head1 SEE ALSO | ||
55 | |||
56 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
57 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, | ||
58 | L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
59 | L<ERR_print_errors(3)|ERR_print_errors(3)> | ||
60 | |||
61 | =head1 HISTORY | ||
62 | |||
63 | ERR_error_string() is available in all versions of SSLeay and OpenSSL. | ||
64 | |||
65 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_get_error.pod b/src/lib/libcrypto/doc/ERR_get_error.pod new file mode 100644 index 0000000000..75ece00d97 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_get_error.pod | |||
@@ -0,0 +1,62 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_get_error, ERR_peek_error - obtain error code | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | unsigned long ERR_get_error(void); | ||
12 | unsigned long ERR_peek_error(void); | ||
13 | |||
14 | unsigned long ERR_get_error_line(const char **file, int *line); | ||
15 | unsigned long ERR_peek_error_line(const char **file, int *line); | ||
16 | |||
17 | unsigned long ERR_get_error_line_data(const char **file, int *line, | ||
18 | const char **data, int *flags); | ||
19 | unsigned long ERR_peek_error_line_data(const char **file, int *line, | ||
20 | const char **data, int *flags); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | ERR_get_error() returns the last error code from the thread's error | ||
25 | queue and removes the entry. This function can be called repeatedly | ||
26 | until there are no more error codes to return. | ||
27 | |||
28 | ERR_peek_error() returns the last error code from the thread's | ||
29 | error queue without modifying it. | ||
30 | |||
31 | See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about | ||
32 | location and reason of the error, and | ||
33 | L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error | ||
34 | messages. | ||
35 | |||
36 | ERR_get_error_line() and ERR_peek_error_line() are the same as the | ||
37 | above, but they additionally store the file name and line number where | ||
38 | the error occurred in *B<file> and *B<line>, unless these are B<NULL>. | ||
39 | |||
40 | ERR_get_error_line_data() and ERR_peek_error_line_data() store | ||
41 | additional data and flags associated with the error code in *B<data> | ||
42 | and *B<flags>, unless these are B<NULL>. *B<data> contains a string | ||
43 | if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by Malloc(), | ||
44 | *B<flags>&B<ERR_TXT_MALLOCED> is true. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | The error code, or 0 if there is no error in the queue. | ||
49 | |||
50 | =head1 SEE ALSO | ||
51 | |||
52 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, | ||
53 | L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> | ||
54 | |||
55 | =head1 HISTORY | ||
56 | |||
57 | ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and | ||
58 | ERR_peek_error_line() are available in all versions of SSLeay and | ||
59 | OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() | ||
60 | were added in SSLeay 0.9.0. | ||
61 | |||
62 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod b/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod new file mode 100644 index 0000000000..9bdec75a46 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod | |||
@@ -0,0 +1,46 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - | ||
6 | load and free error strings | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | void ERR_load_crypto_strings(void); | ||
13 | void ERR_free_strings(void); | ||
14 | |||
15 | #include <openssl/ssl.h> | ||
16 | |||
17 | void SSL_load_error_strings(void); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | ERR_load_crypto_strings() registers the error strings for all | ||
22 | B<libcrypto> functions. SSL_load_error_strings() does the same, | ||
23 | but also registers the B<libssl> error strings. | ||
24 | |||
25 | One of these functions should be called before generating | ||
26 | textual error messages. However, this is not required when memory | ||
27 | usage is an issue. | ||
28 | |||
29 | ERR_free_strings() frees all previously loaded error strings. | ||
30 | |||
31 | =head1 RETURN VALUES | ||
32 | |||
33 | ERR_load_crypto_strings(), SSL_load_error_strings() and | ||
34 | ERR_free_strings() return no values. | ||
35 | |||
36 | =head1 SEE ALSO | ||
37 | |||
38 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> | ||
39 | |||
40 | =head1 HISTORY | ||
41 | |||
42 | ERR_load_error_strings(), SSL_load_error_strings() and | ||
43 | ERR_free_strings() are available in all versions of SSLeay and | ||
44 | OpenSSL. | ||
45 | |||
46 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_load_strings.pod b/src/lib/libcrypto/doc/ERR_load_strings.pod new file mode 100644 index 0000000000..5acdd0edbc --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_load_strings.pod | |||
@@ -0,0 +1,54 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load | ||
6 | arbitrary error strings | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | void ERR_load_strings(int lib, ERR_STRING_DATA str[]); | ||
13 | |||
14 | int ERR_get_next_error_library(void); | ||
15 | |||
16 | unsigned long ERR_PACK(int lib, int func, int reason); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | ERR_load_strings() registers error strings for library number B<lib>. | ||
21 | |||
22 | B<str> is an array of error string data: | ||
23 | |||
24 | typedef struct ERR_string_data_st | ||
25 | { | ||
26 | unsigned long error; | ||
27 | char *string; | ||
28 | } ERR_STRING_DATA; | ||
29 | |||
30 | The error code is generated from the library number and a function and | ||
31 | reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). | ||
32 | ERR_PACK() is a macro. | ||
33 | |||
34 | The last entry in the array is {0,0}. | ||
35 | |||
36 | ERR_get_next_error_library() can be used to assign library numbers | ||
37 | to user libraries at runtime. | ||
38 | |||
39 | =head1 RETURN VALUE | ||
40 | |||
41 | ERR_load_strings() returns no value. ERR_PACK() return the error code. | ||
42 | ERR_get_next_error_library() returns a new library number. | ||
43 | |||
44 | =head1 SEE ALSO | ||
45 | |||
46 | L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> | ||
47 | |||
48 | =head1 HISTORY | ||
49 | |||
50 | ERR_load_error_strings() and ERR_PACK() are available in all versions | ||
51 | of SSLeay and OpenSSL. ERR_get_next_error_library() was added in | ||
52 | SSLeay 0.9.0. | ||
53 | |||
54 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_print_errors.pod b/src/lib/libcrypto/doc/ERR_print_errors.pod new file mode 100644 index 0000000000..b100a5fa2b --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_print_errors.pod | |||
@@ -0,0 +1,51 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_print_errors, ERR_print_errors_fp - print error messages | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_print_errors(BIO *bp); | ||
12 | void ERR_print_errors_fp(FILE *fp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | ERR_print_errors() is a convenience function that prints the error | ||
17 | strings for all errors that OpenSSL has recorded to B<bp>, thus | ||
18 | emptying the error queue. | ||
19 | |||
20 | ERR_print_errors_fp() is the same, except that the output goes to a | ||
21 | B<FILE>. | ||
22 | |||
23 | |||
24 | The error strings will have the following format: | ||
25 | |||
26 | [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] | ||
27 | |||
28 | I<error code> is an 8 digit hexadecimal number. I<library name>, | ||
29 | I<function name> and I<reason string> are ASCII text, as is I<optional | ||
30 | text message> if one was set for the respective error code. | ||
31 | |||
32 | If there is no text string registered for the given error code, | ||
33 | the error string will contain the numeric code. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | ERR_print_errors() and ERR_print_errors_fp() return no values. | ||
38 | |||
39 | =head1 SEE ALSO | ||
40 | |||
41 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, | ||
42 | L<ERR_get_error(3)|ERR_get_error(3)>, | ||
43 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, | ||
44 | L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
45 | |||
46 | =head1 HISTORY | ||
47 | |||
48 | ERR_print_errors() and ERR_print_errors_fp() | ||
49 | are available in all versions of SSLeay and OpenSSL. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_put_error.pod b/src/lib/libcrypto/doc/ERR_put_error.pod new file mode 100644 index 0000000000..acd241fbe4 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_put_error.pod | |||
@@ -0,0 +1,44 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_put_error, ERR_add_error_data - record an error | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_put_error(int lib, int func, int reason, const char *file, | ||
12 | int line); | ||
13 | |||
14 | void ERR_add_error_data(int num, ...); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | ERR_put_error() adds an error code to the thread's error queue. It | ||
19 | signals that the error of reason code B<reason> occurred in function | ||
20 | B<func> of library B<lib>, in line number B<line> of B<file>. | ||
21 | This function is usually called by a macro. | ||
22 | |||
23 | ERR_add_error_data() associates the concatenation of its B<num> string | ||
24 | arguments with the error code added last. | ||
25 | |||
26 | L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register | ||
27 | error strings so that the application can a generate human-readable | ||
28 | error messages for the error code. | ||
29 | |||
30 | =head1 RETURN VALUES | ||
31 | |||
32 | ERR_put_error() and ERR_add_error_data() return | ||
33 | no values. | ||
34 | |||
35 | =head1 SEE ALSO | ||
36 | |||
37 | L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> | ||
38 | |||
39 | =head1 HISTORY | ||
40 | |||
41 | ERR_put_error() is available in all versions of SSLeay and OpenSSL. | ||
42 | ERR_add_error_data() was added in SSLeay 0.9.0. | ||
43 | |||
44 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_remove_state.pod b/src/lib/libcrypto/doc/ERR_remove_state.pod new file mode 100644 index 0000000000..ebcdc0f5a5 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR_remove_state.pod | |||
@@ -0,0 +1,34 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_remove_state - free a thread's error queue | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_remove_state(unsigned long pid); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | ERR_remove_state() frees the error queue associated with thread B<pid>. | ||
16 | If B<pid> == 0, the current thread will have its error queue removed. | ||
17 | |||
18 | Since error queue data structures are allocated automatically for new | ||
19 | threads, they must be freed when threads are terminated in oder to | ||
20 | avoid memory leaks. | ||
21 | |||
22 | =head1 RETURN VALUE | ||
23 | |||
24 | ERR_remove_state() returns no value. | ||
25 | |||
26 | =head1 SEE ALSO | ||
27 | |||
28 | L<err(3)|err(3)> | ||
29 | |||
30 | =head1 HISTORY | ||
31 | |||
32 | ERR_remove_state() is available in all versions of SSLeay and OpenSSL. | ||
33 | |||
34 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod new file mode 100644 index 0000000000..345b1ddfa7 --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_DigestInit.pod | |||
@@ -0,0 +1,197 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
12 | void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
13 | void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, | ||
14 | unsigned int *s); | ||
15 | |||
16 | #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ | ||
17 | |||
18 | int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); | ||
19 | |||
20 | #define EVP_MD_type(e) ((e)->type) | ||
21 | #define EVP_MD_pkey_type(e) ((e)->pkey_type) | ||
22 | #define EVP_MD_size(e) ((e)->md_size) | ||
23 | #define EVP_MD_block_size(e) ((e)->block_size) | ||
24 | |||
25 | #define EVP_MD_CTX_md(e) (e)->digest) | ||
26 | #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) | ||
27 | #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) | ||
28 | #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) | ||
29 | |||
30 | EVP_MD *EVP_md_null(void); | ||
31 | EVP_MD *EVP_md2(void); | ||
32 | EVP_MD *EVP_md5(void); | ||
33 | EVP_MD *EVP_sha(void); | ||
34 | EVP_MD *EVP_sha1(void); | ||
35 | EVP_MD *EVP_dss(void); | ||
36 | EVP_MD *EVP_dss1(void); | ||
37 | EVP_MD *EVP_mdc2(void); | ||
38 | EVP_MD *EVP_ripemd160(void); | ||
39 | |||
40 | const EVP_MD *EVP_get_digestbyname(const char *name); | ||
41 | #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) | ||
42 | #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) | ||
43 | |||
44 | =head1 DESCRIPTION | ||
45 | |||
46 | The EVP digest routines are a high level interface to message digests. | ||
47 | |||
48 | EVP_DigestInit() initialises a digest context B<ctx> to use a digest | ||
49 | B<type>: this will typically be supplied by a function such as | ||
50 | EVP_sha1(). | ||
51 | |||
52 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
53 | digest context B<ctx>. This funtion can be called several times on the | ||
54 | same B<ctx> to hash additional data. | ||
55 | |||
56 | EVP_DigestFinal() retrieves the digest value from B<ctx> and places | ||
57 | it in B<md>. If the B<s> parameter is not NULL then the number of | ||
58 | bytes of data written (i.e. the length of the digest) will be written | ||
59 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | ||
60 | After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate() | ||
61 | can be made, but EVP_DigestInit() can be called to initialiase a new | ||
62 | digest operation. | ||
63 | |||
64 | EVP_MD_CTX_copy() can be used to copy the message digest state from | ||
65 | B<in> to B<out>. This is useful if large amounts of data are to be | ||
66 | hashed which only differ in the last few bytes. | ||
67 | |||
68 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest | ||
69 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the | ||
70 | hash. | ||
71 | |||
72 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the | ||
73 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. | ||
74 | |||
75 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER | ||
76 | representing the given message digest when passed an B<EVP_MD> structure. | ||
77 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is | ||
78 | normally used when setting ASN1 OIDs. | ||
79 | |||
80 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed | ||
81 | B<EVP_MD_CTX>. | ||
82 | |||
83 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated | ||
84 | with this digest. For example EVP_sha1() is associated with RSA so this will | ||
85 | return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature | ||
86 | algorithms may not be retained in future versions of OpenSSL. | ||
87 | |||
88 | EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() | ||
89 | return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest | ||
90 | algorithms respectively. The associated signature algorithm is RSA in each case. | ||
91 | |||
92 | EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest | ||
93 | algorithms but using DSS (DSA) for the signature algorithm. | ||
94 | |||
95 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it | ||
96 | returns is of zero length. | ||
97 | |||
98 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
99 | return an B<EVP_MD> structure when passed a digest name, a digest NID or | ||
100 | an ASN1_OBJECT structure respectively. The digest table must be initialised | ||
101 | using, for example, OpenSSL_add_all_digests() for these functions to work. | ||
102 | |||
103 | =head1 RETURN VALUES | ||
104 | |||
105 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. | ||
106 | |||
107 | EVP_MD_CTX_copy() returns 1 if successful or 0 for failure. | ||
108 | |||
109 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | ||
110 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | ||
111 | |||
112 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), | ||
113 | EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block | ||
114 | size in bytes. | ||
115 | |||
116 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), | ||
117 | EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the | ||
118 | corresponding EVP_MD structures. | ||
119 | |||
120 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
121 | return either an B<EVP_MD> structure or NULL if an error occurs. | ||
122 | |||
123 | =head1 NOTES | ||
124 | |||
125 | The B<EVP> interface to message digests should almost always be used in | ||
126 | preference to the low level interfaces. This is because the code then becomes | ||
127 | transparent to the digest used and much more flexible. | ||
128 | |||
129 | SHA1 is the digest of choice for new applications. The other digest algorithms | ||
130 | are still in common use. | ||
131 | |||
132 | =head1 EXAMPLE | ||
133 | |||
134 | This example digests the data "Test Message\n" and "Hello World\n", using the | ||
135 | digest name passed on the command line. | ||
136 | |||
137 | #include <stdio.h> | ||
138 | #include <openssl/evp.h> | ||
139 | |||
140 | main(int argc, char *argv[]) | ||
141 | { | ||
142 | EVP_MD_CTX mdctx; | ||
143 | const EVP_MD *md; | ||
144 | char mess1[] = "Test Message\n"; | ||
145 | char mess2[] = "Hello World\n"; | ||
146 | unsigned char md_value[EVP_MAX_MD_SIZE]; | ||
147 | int md_len, i; | ||
148 | |||
149 | OpenSSL_add_all_digests(); | ||
150 | |||
151 | if(!argv[1]) { | ||
152 | printf("Usage: mdtest digestname\n"); | ||
153 | exit(1); | ||
154 | } | ||
155 | |||
156 | md = EVP_get_digestbyname(argv[1]); | ||
157 | |||
158 | if(!md) { | ||
159 | printf("Unknown message digest %s\n", argv[1]); | ||
160 | exit(1); | ||
161 | } | ||
162 | |||
163 | EVP_DigestInit(&mdctx, md); | ||
164 | EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); | ||
165 | EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); | ||
166 | EVP_DigestFinal(&mdctx, md_value, &md_len); | ||
167 | |||
168 | printf("Digest is: "); | ||
169 | for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); | ||
170 | printf("\n"); | ||
171 | } | ||
172 | |||
173 | =head1 BUGS | ||
174 | |||
175 | Several of the functions do not return values: maybe they should. Although the | ||
176 | internal digest operations will never fail some future hardware based operations | ||
177 | might. | ||
178 | |||
179 | The link between digests and signing algorithms results in a situation where | ||
180 | EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS | ||
181 | even though they are identical digests. | ||
182 | |||
183 | The size of an B<EVP_MD_CTX> structure is determined at compile time: this results | ||
184 | in code that must be recompiled if the size of B<EVP_MD_CTX> increases. | ||
185 | |||
186 | =head1 SEE ALSO | ||
187 | |||
188 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
189 | L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, | ||
190 | L<sha(3)|sha(3)>, L<digest(1)|digest(1)> | ||
191 | |||
192 | =head1 HISTORY | ||
193 | |||
194 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are | ||
195 | available in all versions of SSLeay and OpenSSL. | ||
196 | |||
197 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_EncryptInit.pod b/src/lib/libcrypto/doc/EVP_EncryptInit.pod new file mode 100644 index 0000000000..77ed4ccdba --- /dev/null +++ b/src/lib/libcrypto/doc/EVP_EncryptInit.pod | |||
@@ -0,0 +1,224 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | void EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
12 | unsigned char *key, unsigned char *iv); | ||
13 | void EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
14 | int *outl, unsigned char *in, int inl); | ||
15 | void EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
16 | int *outl); | ||
17 | |||
18 | void EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
19 | unsigned char *key, unsigned char *iv); | ||
20 | void EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
21 | int *outl, unsigned char *in, int inl); | ||
22 | int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
23 | int *outl); | ||
24 | |||
25 | void EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
26 | unsigned char *key, unsigned char *iv, int enc); | ||
27 | void EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
28 | int *outl, unsigned char *in, int inl); | ||
29 | int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
30 | int *outl); | ||
31 | |||
32 | void EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); | ||
33 | |||
34 | const EVP_CIPHER *EVP_get_cipherbyname(const char *name); | ||
35 | #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) | ||
36 | #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) | ||
37 | |||
38 | #define EVP_CIPHER_nid(e) ((e)->nid) | ||
39 | #define EVP_CIPHER_block_size(e) ((e)->block_size) | ||
40 | #define EVP_CIPHER_key_length(e) ((e)->key_len) | ||
41 | #define EVP_CIPHER_iv_length(e) ((e)->iv_len) | ||
42 | |||
43 | int EVP_CIPHER_type(const EVP_CIPHER *ctx); | ||
44 | #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) | ||
45 | #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) | ||
46 | #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) | ||
47 | #define EVP_CIPHER_CTX_key_length(e) ((e)->cipher->key_len) | ||
48 | #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) | ||
49 | #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) | ||
50 | |||
51 | int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | ||
52 | int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | ||
53 | |||
54 | =head1 DESCRIPTION | ||
55 | |||
56 | The EVP cipher routines are a high level interface to certain | ||
57 | symmetric ciphers. | ||
58 | |||
59 | EVP_EncryptInit() initialises a cipher context B<ctx> for encryption | ||
60 | with cipher B<type>. B<type> is normally supplied by a function such | ||
61 | as EVP_des_cbc() . B<key> is the symmetric key to use and B<iv> is the | ||
62 | IV to use (if necessary), the actual number of bytes used for the | ||
63 | key and IV depends on the cipher. It is possible to set all parameters | ||
64 | to NULL except B<type> in an initial call and supply the remaining | ||
65 | parameters in subsequent calls. This is normally done when the | ||
66 | EVP_CIPHER_asn1_to_param() function is called to set the cipher | ||
67 | parameters from an ASN1 AlgorithmIdentifier and the key from a | ||
68 | different source. | ||
69 | |||
70 | EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and | ||
71 | writes the encrypted version to B<out>. This function can be called | ||
72 | multiple times to encrypt successive blocks of data. The amount | ||
73 | of data written depends on the block alignment of the encrypted data: | ||
74 | as a result the amount of data written may be anything from zero bytes | ||
75 | to (inl + cipher_block_size - 1) so B<outl> should contain sufficient | ||
76 | room. The actual number of bytes written is placed in B<outl>. | ||
77 | |||
78 | EVP_EncryptFinal() encrypts the "final" data, that is any data that | ||
79 | remains in a partial block. It uses L<standard block padding|/NOTES> (aka PKCS | ||
80 | padding). The encrypted final data is written to B<out> which should | ||
81 | have sufficient space for one cipher block. The number of bytes written | ||
82 | is placed in B<outl>. After this function is called the encryption operation | ||
83 | is finished and no further calls to EVP_EncryptUpdate() should be made. | ||
84 | |||
85 | EVP_DecryptInit(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the | ||
86 | corresponding decryption operations. EVP_DecryptFinal() will return an | ||
87 | error code if the final block is not correctly formatted. The parameters | ||
88 | and restrictions are identical to the encryption operations except that | ||
89 | the decrypted data buffer B<out> passed to EVP_DecryptUpdate() should | ||
90 | have sufficient room for (B<inl> + cipher_block_size) bytes unless the | ||
91 | cipher block size is 1 in which case B<inl> bytes is sufficient. | ||
92 | |||
93 | EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions | ||
94 | that can be used for decryption or encryption. The operation performed | ||
95 | depends on the value of the B<enc> parameter. It should be set to 1 for | ||
96 | encryption and 0 for decryption. | ||
97 | |||
98 | EVP_CIPHER_CTX_cleanup() clears all information from a cipher context. | ||
99 | It should be called after all operations using a cipher are complete | ||
100 | so sensitive information does not remain in memory. | ||
101 | |||
102 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | ||
103 | return an EVP_CIPHER structure when passed a cipher name, a NID or an | ||
104 | ASN1_OBJECT structure. | ||
105 | |||
106 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when | ||
107 | passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID | ||
108 | value is an internal value which may not have a corresponding OBJECT | ||
109 | IDENTIFIER. | ||
110 | |||
111 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key | ||
112 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | ||
113 | structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length | ||
114 | for all ciphers. | ||
115 | |||
116 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV | ||
117 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. | ||
118 | It will return zero if the cipher does not use an IV. The constant | ||
119 | B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. | ||
120 | |||
121 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block | ||
122 | size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | ||
123 | structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block | ||
124 | length for all ciphers. | ||
125 | |||
126 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed | ||
127 | cipher or context. This "type" is the actual NID of the cipher OBJECT | ||
128 | IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and | ||
129 | 128 bit RC2 have the same NID. If the cipher does not have an object | ||
130 | identifier or does not have ASN1 support this function will return | ||
131 | B<NID_undef>. | ||
132 | |||
133 | EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed | ||
134 | an B<EVP_CIPHER_CTX> structure. | ||
135 | |||
136 | EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based | ||
137 | on the passed cipher. This will typically include any parameters and an | ||
138 | IV. The cipher IV (if any) must be set when this call is made. This call | ||
139 | should be made before the cipher is actually "used" (before any | ||
140 | EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function | ||
141 | may fail if the cipher does not have any ASN1 support. | ||
142 | |||
143 | EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 | ||
144 | AlgorithmIdentifier "parameter". The precise effect depends on the cipher | ||
145 | In the case of RC2, for example, it will set the IV and effective key length. | ||
146 | This function should be called after the base cipher type is set but before | ||
147 | the key is set. For example EVP_CipherInit() will be called with the IV and | ||
148 | key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally | ||
149 | EVP_CipherInit() again with all parameters except the key set to NULL. It is | ||
150 | possible for this function to fail if the cipher does not have any ASN1 support | ||
151 | or the parameters cannot be set (for example the RC2 effective key length | ||
152 | does not have an B<EVP_CIPHER> structure). | ||
153 | |||
154 | =head1 RETURN VALUES | ||
155 | |||
156 | EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() do not return | ||
157 | values. | ||
158 | |||
159 | EVP_DecryptInit() and EVP_DecryptUpdate() do not return values. | ||
160 | EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success. | ||
161 | |||
162 | EVP_CipherInit() and EVP_CipherUpdate() do not return values. | ||
163 | EVP_CipherFinal() returns 1 for a decryption failure or 1 for success, if | ||
164 | the operation is encryption then it always returns 1. | ||
165 | |||
166 | EVP_CIPHER_CTX_cleanup() does not return a value. | ||
167 | |||
168 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | ||
169 | return an B<EVP_CIPHER> structure or NULL on error. | ||
170 | |||
171 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. | ||
172 | |||
173 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block | ||
174 | size. | ||
175 | |||
176 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key | ||
177 | length. | ||
178 | |||
179 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV | ||
180 | length or zero if the cipher does not use an IV. | ||
181 | |||
182 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's | ||
183 | OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. | ||
184 | |||
185 | EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. | ||
186 | |||
187 | EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for | ||
188 | success or zero for failure. | ||
189 | |||
190 | =head1 NOTES | ||
191 | |||
192 | Where possible the B<EVP> interface to symmetric ciphers should be used in | ||
193 | preference to the low level interfaces. This is because the code then becomes | ||
194 | transparent to the cipher used and much more flexible. | ||
195 | |||
196 | PKCS padding works by adding B<n> padding bytes of value B<n> to make the total | ||
197 | length of the encrypted data a multiple of the block size. Padding is always | ||
198 | added so if the data is already a multiple of the block size B<n> will equal | ||
199 | the block size. For example if the block size is 8 and 11 bytes are to be | ||
200 | encrypted then 5 padding bytes of value 5 will be added. | ||
201 | |||
202 | When decrypting the final block is checked to see if it has the correct form. | ||
203 | |||
204 | Although the decryption operation can produce an error, it is not a strong | ||
205 | test that the input data or key is correct. A random block has better than | ||
206 | 1 in 256 chance of being of the correct format and problems with the | ||
207 | input data earlier on will not produce a final decrypt error. | ||
208 | |||
209 | =head1 BUGS | ||
210 | |||
211 | The current B<EVP> cipher interface is not as flexible as it should be. Only | ||
212 | certain "spot" encryption algorithms can be used for ciphers which have various | ||
213 | parameters associated with them (RC2, RC5 for example) this is inadequate. | ||
214 | |||
215 | Several of the functions do not return error codes because the software versions | ||
216 | can never fail. This is not true of hardware versions. | ||
217 | |||
218 | =head1 SEE ALSO | ||
219 | |||
220 | L<evp(3)|evp(3)> | ||
221 | |||
222 | =head1 HISTORY | ||
223 | |||
224 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod b/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod new file mode 100644 index 0000000000..b0b1058d19 --- /dev/null +++ b/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod | |||
@@ -0,0 +1,46 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OPENSSL_VERSION_NUMBER, SSLeay - get OpenSSL version number | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/opensslv.h> | ||
10 | #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL | ||
11 | |||
12 | #include <openssl/crypto.h> | ||
13 | long SSLeay(void); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | OPENSSL_VERSION_NUMBER is a numeric release version identifier: | ||
18 | |||
19 | MMNNFFRBB major minor fix final beta/patch | ||
20 | |||
21 | for example | ||
22 | |||
23 | 0x000904100 == 0.9.4 release | ||
24 | 0x000905000 == 0.9.5 dev | ||
25 | |||
26 | Versions prior to 0.9.3 have identifiers E<lt> 0x0930. | ||
27 | For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. | ||
28 | |||
29 | SSLeay() returns this number. The return value can be compared to the | ||
30 | macro to make sure that the correct version of the library has been | ||
31 | loaded, especially when using DLLs on Windows systems. | ||
32 | |||
33 | =head1 RETURN VALUE | ||
34 | |||
35 | The version number. | ||
36 | |||
37 | =head1 SEE ALSO | ||
38 | |||
39 | L<crypto(3)|crypto(3)> | ||
40 | |||
41 | =head1 HISTORY | ||
42 | |||
43 | SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL. | ||
44 | OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. | ||
45 | |||
46 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod b/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod new file mode 100644 index 0000000000..1300fe190c --- /dev/null +++ b/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod | |||
@@ -0,0 +1,65 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OpenSSL_add_all_algorithms() - add algorithms to internal table | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | void OpenSSL_add_all_algorithms(void); | ||
12 | void OpenSSL_add_all_ciphers(void); | ||
13 | void OpenSSL_add_all_digests(void); | ||
14 | |||
15 | void EVP_cleanup(void); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | OpenSSL keeps an internal table of digest algorithms and ciphers. It uses | ||
20 | this table to lookup ciphers via functions such as EVP_get_cipher_byname(). | ||
21 | |||
22 | OpenSSL_add_all_digests() adds all digest algorithms to the table. | ||
23 | |||
24 | OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and | ||
25 | ciphers). | ||
26 | |||
27 | OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including | ||
28 | password based encryption algorithms. | ||
29 | |||
30 | EVP_cleanup() removes all ciphers and digests from the table. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | None of the functions return a value. | ||
35 | |||
36 | =head1 NOTES | ||
37 | |||
38 | A typical application will will call OpenSSL_add_all_algorithms() initially and | ||
39 | EVP_cleanup() before exiting. | ||
40 | |||
41 | An application does not need to add algorithms to use them explicitly, for example | ||
42 | by EVP_sha1(). It just needs to add them if it (or any of the functions it calls) | ||
43 | needs to lookup algorithms. | ||
44 | |||
45 | The cipher and digest lookup functions are used in many parts of the library. If | ||
46 | the table is not initialised several functions will misbehave and complain they | ||
47 | cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries. | ||
48 | This is a common query in the OpenSSL mailing lists. | ||
49 | |||
50 | Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a | ||
51 | statically linked executable can be quite large. If this is important it is possible | ||
52 | to just add the required ciphers and digests. | ||
53 | |||
54 | =head1 BUGS | ||
55 | |||
56 | Although the functions do not return error codes it is possible for them to fail. | ||
57 | This will only happen as a result of a memory allocation failure so this is not | ||
58 | too much of a problem in practice. | ||
59 | |||
60 | =head1 SEE ALSO | ||
61 | |||
62 | L<evp(3)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, | ||
63 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> | ||
64 | |||
65 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_add.pod b/src/lib/libcrypto/doc/RAND_add.pod new file mode 100644 index 0000000000..0a13ec2a92 --- /dev/null +++ b/src/lib/libcrypto/doc/RAND_add.pod | |||
@@ -0,0 +1,68 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_add, RAND_seed, RAND_screen - add entropy to the PRNG | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_seed(const void *buf, int num); | ||
12 | |||
13 | void RAND_add(const void *buf, int num, double entropy); | ||
14 | |||
15 | int RAND_status(void); | ||
16 | |||
17 | void RAND_screen(void); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, | ||
22 | if the data at B<buf> are unpredictable to an adversary, this | ||
23 | increases the uncertainty about the state and makes the PRNG output | ||
24 | less predictable. Suitable input comes from user interaction (random | ||
25 | key presses, mouse movements) and certain hardware events. The | ||
26 | B<entropy> argument is (the lower bound of) an estimate of how much | ||
27 | randomness is contained in B<buf>, measured in bytes. Details about | ||
28 | sources of randomness and how to estimate their entropy can be found | ||
29 | in the literature, e.g. RFC 1750. | ||
30 | |||
31 | RAND_add() may be called with sensitive data such as user entered | ||
32 | passwords. The seed values cannot be recovered from the PRNG output. | ||
33 | |||
34 | OpenSSL makes sure that the PRNG state is unique for each thread. On | ||
35 | systems that provide C</dev/urandom>, the randomness device is used | ||
36 | to seed the PRNG transparently. However, on all other systems, the | ||
37 | application is responsible for seeding the PRNG by calling RAND_add(), | ||
38 | L<RAND_egd(3)|RAND_egd(3)> | ||
39 | or L<RAND_load_file(3)|RAND_load_file(3)>. | ||
40 | |||
41 | RAND_seed() is equivalent to RAND_add() when B<num == entropy>. | ||
42 | |||
43 | The RAND_screen() function is available for the convenience of Windows | ||
44 | programmers. It adds the current contents of the screen to the PRNG. | ||
45 | For applications that can catch Windows events, seeding the PRNG with | ||
46 | the parameters of B<WM_MOUSEMOVE> events is a significantly better | ||
47 | source of randomness. It should be noted that both methods cannot be | ||
48 | used on servers that run without user interaction. | ||
49 | |||
50 | =head1 RETURN VALUES | ||
51 | |||
52 | RAND_status() returns 1 if the PRNG has been seeded with enough data, | ||
53 | 0 otherwise. | ||
54 | |||
55 | The other functions do not return values. | ||
56 | |||
57 | =head1 SEE ALSO | ||
58 | |||
59 | L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, | ||
60 | L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> | ||
61 | |||
62 | =head1 HISTORY | ||
63 | |||
64 | RAND_seed() and RAND_screen() are available in all versions of SSLeay | ||
65 | and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL | ||
66 | 0.9.5. | ||
67 | |||
68 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_bytes.pod b/src/lib/libcrypto/doc/RAND_bytes.pod new file mode 100644 index 0000000000..b6ebd50527 --- /dev/null +++ b/src/lib/libcrypto/doc/RAND_bytes.pod | |||
@@ -0,0 +1,46 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_bytes, RAND_pseudo_bytes - generate random data | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | int RAND_bytes(unsigned char *buf, int num); | ||
12 | |||
13 | int RAND_pseudo_bytes(unsigned char *buf, int num); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes | ||
18 | into B<buf>. An error occurs if the PRNG has not been seeded with | ||
19 | enough randomness to ensure an unpredictable byte sequence. | ||
20 | |||
21 | RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. | ||
22 | Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be | ||
23 | unique if they are of sufficient length, but are not necessarily | ||
24 | unpredictable. They can be used for non-cryptographic purposes and for | ||
25 | certain purposes in cryptographic protocols, but usually not for key | ||
26 | generation etc. | ||
27 | |||
28 | =head1 RETURN VALUES | ||
29 | |||
30 | RAND_bytes() returns 1 on success, 0 otherwise. The error code can be | ||
31 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the | ||
32 | bytes generated are cryptographically strong, 0 otherwise. Both | ||
33 | functions return -1 if they are not supported by the current RAND | ||
34 | method. | ||
35 | |||
36 | =head1 SEE ALSO | ||
37 | |||
38 | L<rand(3)|rand(3)>, L<err(3)|err(3)>, L<RAND_add(3)|RAND_add(3)> | ||
39 | |||
40 | =head1 HISTORY | ||
41 | |||
42 | RAND_bytes() is available in all versions of SSLeay and OpenSSL. It | ||
43 | has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added | ||
44 | in OpenSSL 0.9.5. | ||
45 | |||
46 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_cleanup.pod b/src/lib/libcrypto/doc/RAND_cleanup.pod new file mode 100644 index 0000000000..3a8f0749a8 --- /dev/null +++ b/src/lib/libcrypto/doc/RAND_cleanup.pod | |||
@@ -0,0 +1,29 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_cleanup - erase the PRNG state | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_cleanup(void); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | RAND_cleanup() erases the memory used by the PRNG. | ||
16 | |||
17 | =head1 RETURN VALUE | ||
18 | |||
19 | RAND_cleanup() returns no value. | ||
20 | |||
21 | =head1 SEE ALSO | ||
22 | |||
23 | L<rand(3)|rand(3)> | ||
24 | |||
25 | =head1 HISTORY | ||
26 | |||
27 | RAND_cleanup() is available in all versions of SSLeay and OpenSSL. | ||
28 | |||
29 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_load_file.pod b/src/lib/libcrypto/doc/RAND_load_file.pod new file mode 100644 index 0000000000..8dd700ca3d --- /dev/null +++ b/src/lib/libcrypto/doc/RAND_load_file.pod | |||
@@ -0,0 +1,53 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | const char *RAND_file_name(char *buf, int num); | ||
12 | |||
13 | int RAND_load_file(const char *filename, long max_bytes); | ||
14 | |||
15 | int RAND_write_file(const char *filename); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RAND_file_name() generates a default path for the random seed | ||
20 | file. B<buf> points to a buffer of size B<num> in which to store the | ||
21 | filename. The seed file is $RANDFILE if that environment variable is | ||
22 | set, $HOME/.rnd otherwise. If $HOME is not set either, or B<num> is | ||
23 | too small for the path name, an error occurs. | ||
24 | |||
25 | RAND_load_file() reads a number of bytes from file B<filename> and | ||
26 | adds them to the PRNG. If B<max_bytes> is non-negative, | ||
27 | up to to B<max_bytes> are read; starting with OpenSSL 0.9.5, | ||
28 | if B<max_bytes> is -1, the complete file is read. | ||
29 | |||
30 | RAND_write_file() writes a number of random bytes (currently 1024) to | ||
31 | file B<filename> which can be used to initialize the PRNG by calling | ||
32 | RAND_load_file() in a later session. | ||
33 | |||
34 | =head1 RETURN VALUES | ||
35 | |||
36 | RAND_load_file() returns the number of bytes read. | ||
37 | |||
38 | RAND_write_file() returns the number of bytes written, and -1 if the | ||
39 | bytes written were generated without appropriate seed. | ||
40 | |||
41 | RAND_file_name() returns a pointer to B<buf> on success, and NULL on | ||
42 | error. | ||
43 | |||
44 | =head1 SEE ALSO | ||
45 | |||
46 | L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> | ||
47 | |||
48 | =head1 HISTORY | ||
49 | |||
50 | RAND_load_file(), RAND_write_file() and RAND_file_name() are available in | ||
51 | all versions of SSLeay and OpenSSL. | ||
52 | |||
53 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_set_rand_method.pod b/src/lib/libcrypto/doc/RAND_set_rand_method.pod new file mode 100644 index 0000000000..466e9b8767 --- /dev/null +++ b/src/lib/libcrypto/doc/RAND_set_rand_method.pod | |||
@@ -0,0 +1,57 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_set_rand_method(RAND_METHOD *meth); | ||
12 | |||
13 | RAND_METHOD *RAND_get_rand_method(void); | ||
14 | |||
15 | RAND_METHOD *RAND_SSLeay(void); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | A B<RAND_METHOD> specifies the functions that OpenSSL uses for random | ||
20 | number generation. By modifying the method, alternative | ||
21 | implementations such as hardware RNGs may be used. Initially, the | ||
22 | default is to use the OpenSSL internal implementation. RAND_SSLeay() | ||
23 | returns a pointer to that method. | ||
24 | |||
25 | RAND_set_rand_method() sets the RAND method to B<meth>. | ||
26 | RAND_get_rand_method() returns a pointer to the current method. | ||
27 | |||
28 | =head1 THE RAND_METHOD STRUCTURE | ||
29 | |||
30 | typedef struct rand_meth_st | ||
31 | { | ||
32 | void (*seed)(const void *buf, int num); | ||
33 | int (*bytes)(unsigned char *buf, int num); | ||
34 | void (*cleanup)(void); | ||
35 | void (*add)(const void *buf, int num, int entropy); | ||
36 | int (*pseudorand)(unsigned char *buf, int num); | ||
37 | } RAND_METHOD; | ||
38 | |||
39 | The components point to the implementation of RAND_seed(), | ||
40 | RAND_bytes(), RAND_cleanup(), RAND_add() and RAND_pseudo_rand(). | ||
41 | Each component may be NULL if the function is not implemented. | ||
42 | |||
43 | =head1 RETURN VALUES | ||
44 | |||
45 | RAND_set_rand_method() returns no value. RAND_get_rand_method() and | ||
46 | RAND_SSLeay() return pointers to the respective methods. | ||
47 | |||
48 | =head1 SEE ALSO | ||
49 | |||
50 | L<rand(3)|rand(3)> | ||
51 | |||
52 | =head1 HISTORY | ||
53 | |||
54 | RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are | ||
55 | available in all versions of OpenSSL. | ||
56 | |||
57 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_blinding_on.pod b/src/lib/libcrypto/doc/RSA_blinding_on.pod new file mode 100644 index 0000000000..fd2c69abd8 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_blinding_on.pod | |||
@@ -0,0 +1,43 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); | ||
12 | |||
13 | void RSA_blinding_off(RSA *rsa); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | RSA is vulnerable to timing attacks. In a setup where attackers can | ||
18 | measure the time of RSA decryption or signature operations, blinding | ||
19 | must be used to protect the RSA operation from that attack. | ||
20 | |||
21 | RSA_blinding_on() turns blinding on for key B<rsa> and generates a | ||
22 | random blinding factor. B<ctx> is B<NULL> or a pre-allocated and | ||
23 | initialized B<BN_CTX>. The random number generator must be seeded | ||
24 | prior to calling RSA_blinding_on(). | ||
25 | |||
26 | RSA_blinding_off() turns blinding off and frees the memory used for | ||
27 | the blinding factor. | ||
28 | |||
29 | =head1 RETURN VALUES | ||
30 | |||
31 | RSA_blinding_on() returns 1 on success, and 0 if an error occurred. | ||
32 | |||
33 | RSA_blinding_off() returns no value. | ||
34 | |||
35 | =head1 SEE ALSO | ||
36 | |||
37 | L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> | ||
38 | |||
39 | =head1 HISTORY | ||
40 | |||
41 | RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. | ||
42 | |||
43 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_check_key.pod b/src/lib/libcrypto/doc/RSA_check_key.pod new file mode 100644 index 0000000000..79fed753ad --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_check_key.pod | |||
@@ -0,0 +1,39 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_check_key - validate private RSA keys | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_check_key(RSA *rsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function validates RSA keys. It checks that B<p> and B<q> are | ||
16 | in fact prime, and that B<n = p*q>. | ||
17 | |||
18 | It also checks that B<d*e = 1 mod (p-1*q-1)>, | ||
19 | and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>. | ||
20 | |||
21 | The key's public components may not be B<NULL>. | ||
22 | |||
23 | =head1 RETURN VALUE | ||
24 | |||
25 | RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. | ||
26 | -1 is returned if an error occurs while checking the key. | ||
27 | |||
28 | If the key is invalid or an error occurred, the reason code can be | ||
29 | obtained using L<ERR_get_error(3)|ERR_get_error(3)>. | ||
30 | |||
31 | =head1 SEE ALSO | ||
32 | |||
33 | L<rsa(3)|rsa(3)>, L<err(3)|err(3)> | ||
34 | |||
35 | =head1 HISTORY | ||
36 | |||
37 | RSA_check() appeared in OpenSSL 0.9.4. | ||
38 | |||
39 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_generate_key.pod b/src/lib/libcrypto/doc/RSA_generate_key.pod new file mode 100644 index 0000000000..fdaddbcb13 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_generate_key.pod | |||
@@ -0,0 +1,68 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_generate_key - generate RSA key pair | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | RSA *RSA_generate_key(int num, unsigned long e, | ||
12 | void (*callback)(int,int,void *), void *cb_arg); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | RSA_generate_key() generates a key pair and returns it in a newly | ||
17 | allocated B<RSA> structure. The pseudo-random number generator must | ||
18 | be seeded prior to calling RSA_generate_key(). | ||
19 | |||
20 | The modulus size will be B<num> bits, and the public exponent will be | ||
21 | B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure. | ||
22 | The exponent is an odd number, typically 3 or 65535. | ||
23 | |||
24 | A callback function may be used to provide feedback about the | ||
25 | progress of the key generation. If B<callback> is not B<NULL>, it | ||
26 | will be called as follows: | ||
27 | |||
28 | =over 4 | ||
29 | |||
30 | =item * | ||
31 | |||
32 | While a random prime number is generated, it is called as | ||
33 | described in L<BN_generate_prime(3)|BN_generate_prime(3)>. | ||
34 | |||
35 | =item * | ||
36 | |||
37 | When the n-th randomly generated prime is rejected as not | ||
38 | suitable for the key, B<callback(2, n, cb_arg)> is called. | ||
39 | |||
40 | =item * | ||
41 | |||
42 | When a random p has been found with p-1 relatively prime to B<e>, | ||
43 | it is called as B<callback(3, 0, cb_arg)>. | ||
44 | |||
45 | =back | ||
46 | |||
47 | The process is then repeated for prime q with B<callback(3, 1, cb_arg)>. | ||
48 | |||
49 | =head1 RETURN VALUE | ||
50 | |||
51 | If key generation fails, RSA_generate_key() returns B<NULL>; the | ||
52 | error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
53 | |||
54 | =head1 BUGS | ||
55 | |||
56 | B<callback(2, x, cb_arg)> is used with two different meanings. | ||
57 | |||
58 | RSA_generate_key() goes into an infinite loop for illegal input values. | ||
59 | |||
60 | =head1 SEE ALSO | ||
61 | |||
62 | L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_free(3)|RSA_free(3)> | ||
63 | |||
64 | =head1 HISTORY | ||
65 | |||
66 | The B<cb_arg> argument was added in SSLeay 0.9.0. | ||
67 | |||
68 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod new file mode 100644 index 0000000000..920dc76325 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod | |||
@@ -0,0 +1,122 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_get_ex_new_index(long argl, void *argp, | ||
12 | CRYPTO_EX_new *new_func, | ||
13 | CRYPTO_EX_dup *dup_func, | ||
14 | CRYPTO_EX_free *free_func); | ||
15 | |||
16 | int RSA_set_ex_data(RSA *r, int idx, void *arg); | ||
17 | |||
18 | void *RSA_get_ex_data(RSA *r, int idx); | ||
19 | |||
20 | int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, | ||
21 | int idx, long argl, void *argp); | ||
22 | |||
23 | void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, | ||
24 | int idx, long argl, void *argp); | ||
25 | |||
26 | int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, | ||
27 | int idx, long argl, void *argp); | ||
28 | |||
29 | =head1 DESCRIPTION | ||
30 | |||
31 | Several OpenSSL structures can have application specific data attached to them. | ||
32 | This has several potential uses, it can be used to cache data associated with | ||
33 | a structure (for example the hash of some part of the structure) or some | ||
34 | additional data (for example a handle to the data in an external library). | ||
35 | |||
36 | Since the application data can be anything at all it is passed and retrieved | ||
37 | as a B<void *> type. | ||
38 | |||
39 | The B<RSA_get_ex_new_index()> function is initially called to "register" some | ||
40 | new application specific data. It takes three optional function pointers which | ||
41 | are called when the parent structure (in this case an RSA structure) is | ||
42 | initially created, when it is copied and when it is freed up. If any or all of | ||
43 | these function pointer arguments are not used they should be set to NULL. The | ||
44 | precise manner in which these function pointers are called is described in more | ||
45 | detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer | ||
46 | parameters which will be passed to the supplied functions but which otherwise | ||
47 | have no special meaning. It returns an B<index> which should be stored | ||
48 | (typically in a static variable) and passed used in the B<idx> parameter in | ||
49 | the remaining functions. Each successful call to B<RSA_get_ex_new_index()> | ||
50 | will return an index greater than any previously returned, this is important | ||
51 | because the optional functions are called in order of increasing index value. | ||
52 | |||
53 | B<RSA_set_ex_data()> is used to set application specific data, the data is | ||
54 | supplied in the B<arg> parameter and its precise meaning is up to the | ||
55 | application. | ||
56 | |||
57 | B<RSA_get_ex_data()> is used to retrieve application specific data. The data | ||
58 | is returned to the application, this will be the same value as supplied to | ||
59 | a previous B<RSA_set_ex_data()> call. | ||
60 | |||
61 | B<new_func()> is called when a structure is initially allocated (for example | ||
62 | with B<RSA_new()>. The parent structure members will not have any meaningful | ||
63 | values at this point. This function will typically be used to allocate any | ||
64 | application specific structure. | ||
65 | |||
66 | B<free_func()> is called when a structure is being freed up. The dynamic parent | ||
67 | structure members should not be accessed because they will be freed up when | ||
68 | this function is called. | ||
69 | |||
70 | B<new_func()> and B<free_func()> take the same parameters. B<parent> is a | ||
71 | pointer to the parent RSA structure. B<ptr> is a the application specific data | ||
72 | (this wont be of much use in B<new_func()>. B<ad> is a pointer to the | ||
73 | B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions | ||
74 | B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate | ||
75 | it. The B<idx> parameter is the index: this will be the same value returned by | ||
76 | B<RSA_get_ex_new_index()> when the functions were initially registered. Finally | ||
77 | the B<argl> and B<argp> parameters are the values originally passed to the same | ||
78 | corresponding parameters when B<RSA_get_ex_new_index()> was called. | ||
79 | |||
80 | B<dup_func()> is called when a structure is being copied. Pointers to the | ||
81 | destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and | ||
82 | B<from> parameters respectively. The B<from_d> parameter is passed a pointer to | ||
83 | the source application data when the function is called, when the function returns | ||
84 | the value is copied to the destination: the application can thus modify the data | ||
85 | pointed to by B<from_d> and have different values in the source and destination. | ||
86 | The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> | ||
87 | and B<free_func()>. | ||
88 | |||
89 | =head1 RETURN VALUES | ||
90 | |||
91 | B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid | ||
92 | index value). | ||
93 | |||
94 | B<RSA_set_ex_data()> returns 1 on success or 0 on failure. | ||
95 | |||
96 | B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also | ||
97 | be valid application data but currently it can only fail if given an invalid B<idx> | ||
98 | parameter. | ||
99 | |||
100 | B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. | ||
101 | |||
102 | On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. | ||
103 | |||
104 | =head1 BUGS | ||
105 | |||
106 | B<dup_func()> is currently never called. | ||
107 | |||
108 | The return value of B<new_func()> is ignored. | ||
109 | |||
110 | The B<new_func()> function isn't very useful because no meaningful values are | ||
111 | present in the parent RSA structure when it is called. | ||
112 | |||
113 | =head1 SEE ALSO | ||
114 | |||
115 | L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> | ||
116 | |||
117 | =head1 HISTORY | ||
118 | |||
119 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are | ||
120 | available since SSLeay 0.9.0. | ||
121 | |||
122 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_new.pod b/src/lib/libcrypto/doc/RSA_new.pod new file mode 100644 index 0000000000..f16490ea6a --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_new.pod | |||
@@ -0,0 +1,38 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_new, RSA_free - allocate and free RSA objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | RSA * RSA_new(void); | ||
12 | |||
13 | void RSA_free(RSA *rsa); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | RSA_new() allocates and initializes an B<RSA> structure. | ||
18 | |||
19 | RSA_free() frees the B<RSA> structure and its components. The key is | ||
20 | erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, RSA_new() returns B<NULL> and sets an error | ||
25 | code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns | ||
26 | a pointer to the newly allocated structure. | ||
27 | |||
28 | RSA_free() returns no value. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_generate_key(3)|RSA_generate_key(3)> | ||
33 | |||
34 | =head1 HISTORY | ||
35 | |||
36 | RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. | ||
37 | |||
38 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod b/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod new file mode 100644 index 0000000000..b8f678fe72 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod | |||
@@ -0,0 +1,124 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, | ||
6 | RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, | ||
7 | RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, | ||
8 | RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, | ||
9 | RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption | ||
10 | padding | ||
11 | |||
12 | =head1 SYNOPSIS | ||
13 | |||
14 | #include <openssl/rsa.h> | ||
15 | |||
16 | int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, | ||
17 | unsigned char *f, int fl); | ||
18 | |||
19 | int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, | ||
20 | unsigned char *f, int fl, int rsa_len); | ||
21 | |||
22 | int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, | ||
23 | unsigned char *f, int fl); | ||
24 | |||
25 | int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, | ||
26 | unsigned char *f, int fl, int rsa_len); | ||
27 | |||
28 | int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, | ||
29 | unsigned char *f, int fl, unsigned char *p, int pl); | ||
30 | |||
31 | int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, | ||
32 | unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); | ||
33 | |||
34 | int RSA_padding_add_SSLv23(unsigned char *to, int tlen, | ||
35 | unsigned char *f, int fl); | ||
36 | |||
37 | int RSA_padding_check_SSLv23(unsigned char *to, int tlen, | ||
38 | unsigned char *f, int fl, int rsa_len); | ||
39 | |||
40 | int RSA_padding_add_none(unsigned char *to, int tlen, | ||
41 | unsigned char *f, int fl); | ||
42 | |||
43 | int RSA_padding_check_none(unsigned char *to, int tlen, | ||
44 | unsigned char *f, int fl, int rsa_len); | ||
45 | |||
46 | =head1 DESCRIPTION | ||
47 | |||
48 | The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, | ||
49 | decrypt, sign and verify functions. Normally they should not be called | ||
50 | from application programs. | ||
51 | |||
52 | However, they can also be called directly to implement padding for other | ||
53 | asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and | ||
54 | RSA_padding_check_PKCS1_OAEP() may be used in an application combined | ||
55 | with B<RSA_NO_PADDING> in order to implement OAEP with an encoding | ||
56 | parameter. | ||
57 | |||
58 | RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into | ||
59 | B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> | ||
60 | does not meet the size requirements of the encoding method. | ||
61 | |||
62 | The following encoding methods are implemented: | ||
63 | |||
64 | =over 4 | ||
65 | |||
66 | =item PKCS1_type_1 | ||
67 | |||
68 | PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures | ||
69 | |||
70 | =item PKCS1_type_2 | ||
71 | |||
72 | PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) | ||
73 | |||
74 | =item PKCS1_OAEP | ||
75 | |||
76 | PKCS #1 v2.0 EME-OAEP | ||
77 | |||
78 | =item SSLv23 | ||
79 | |||
80 | PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification | ||
81 | |||
82 | =item none | ||
83 | |||
84 | simply copy the data | ||
85 | |||
86 | =back | ||
87 | |||
88 | The random number generator must be seeded prior to calling | ||
89 | RSA_padding_add_xxx(). | ||
90 | |||
91 | RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain | ||
92 | a valid encoding for a B<rsa_len> byte RSA key in the respective | ||
93 | encoding method and stores the recovered data of at most B<tlen> bytes | ||
94 | (for B<RSA_NO_PADDING>: of size B<tlen>) | ||
95 | at B<to>. | ||
96 | |||
97 | For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter | ||
98 | of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. | ||
99 | |||
100 | =head1 RETURN VALUES | ||
101 | |||
102 | The RSA_padding_add_xxx() functions return 1 on success, 0 on error. | ||
103 | The RSA_padding_check_xxx() functions return the length of the | ||
104 | recovered data, -1 on error. Error codes can be obtained by calling | ||
105 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
106 | |||
107 | =head1 SEE ALSO | ||
108 | |||
109 | L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, | ||
110 | L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, | ||
111 | L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> | ||
112 | |||
113 | =head1 HISTORY | ||
114 | |||
115 | RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), | ||
116 | RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), | ||
117 | RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), | ||
118 | RSA_padding_add_none() and RSA_padding_check_none() appeared in | ||
119 | SSLeay 0.9.0. | ||
120 | |||
121 | RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were | ||
122 | added in OpenSSL 0.9.2b. | ||
123 | |||
124 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_print.pod b/src/lib/libcrypto/doc/RSA_print.pod new file mode 100644 index 0000000000..dd968a5274 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_print.pod | |||
@@ -0,0 +1,48 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_print, RSA_print_fp, DHparams_print, DHparams_print_fp - print | ||
6 | cryptographic parameters | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/rsa.h> | ||
11 | |||
12 | int RSA_print(BIO *bp, RSA *x, int offset); | ||
13 | int RSA_print_fp(FILE *fp, RSA *x, int offset); | ||
14 | |||
15 | #include <openssl/dsa.h> | ||
16 | |||
17 | int DSAparams_print(BIO *bp, DSA *x); | ||
18 | int DSAparams_print_fp(FILE *fp, DSA *x); | ||
19 | int DSA_print(BIO *bp, DSA *x, int offset); | ||
20 | int DSA_print_fp(FILE *fp, DSA *x, int offset); | ||
21 | |||
22 | #include <openssl/dh.h> | ||
23 | |||
24 | int DHparams_print(BIO *bp, DH *x); | ||
25 | int DHparams_print_fp(FILE *fp, DH *x); | ||
26 | |||
27 | =head1 DESCRIPTION | ||
28 | |||
29 | A human-readable hexadecimal output of the components of the RSA | ||
30 | key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>. | ||
31 | |||
32 | The output lines are indented by B<offset> spaces. | ||
33 | |||
34 | =head1 RETURN VALUES | ||
35 | |||
36 | These functions return 1 on success, 0 on error. | ||
37 | |||
38 | =head1 SEE ALSO | ||
39 | |||
40 | L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> | ||
41 | |||
42 | =head1 HISTORY | ||
43 | |||
44 | RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), | ||
45 | DH_print_fp() are available in all versions of SSLeay and OpenSSL. | ||
46 | DSAparams_print() and DSAparams_print_pf() were added in SSLeay 0.8. | ||
47 | |||
48 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_private_encrypt.pod b/src/lib/libcrypto/doc/RSA_private_encrypt.pod new file mode 100644 index 0000000000..6861a98a10 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_private_encrypt.pod | |||
@@ -0,0 +1,69 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_private_encrypt, RSA_public_decrypt - low level signature operations | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_private_encrypt(int flen, unsigned char *from, | ||
12 | unsigned char *to, RSA *rsa, int padding); | ||
13 | |||
14 | int RSA_public_decrypt(int flen, unsigned char *from, | ||
15 | unsigned char *to, RSA *rsa, int padding); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | These functions handle RSA signatures at a low level. | ||
20 | |||
21 | RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a | ||
22 | message digest with an algorithm identifier) using the private key | ||
23 | B<rsa> and stores the signature in B<to>. B<to> must point to | ||
24 | B<RSA_size(rsa)> bytes of memory. | ||
25 | |||
26 | B<padding> denotes one of the following modes: | ||
27 | |||
28 | =over 4 | ||
29 | |||
30 | =item RSA_PKCS1_PADDING | ||
31 | |||
32 | PKCS #1 v1.5 padding. This function does not handle the | ||
33 | B<algorithmIdentifier> specified in PKCS #1. When generating or | ||
34 | verifying PKCS #1 signatures, L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be | ||
35 | used. | ||
36 | |||
37 | =item RSA_NO_PADDING | ||
38 | |||
39 | Raw RSA signature. This mode should I<only> be used to implement | ||
40 | cryptographically sound padding modes in the application code. | ||
41 | Signing user data directly with RSA is insecure. | ||
42 | |||
43 | =back | ||
44 | |||
45 | RSA_public_decrypt() recovers the message digest from the B<flen> | ||
46 | bytes long signature at B<from> using the signer's public key | ||
47 | B<rsa>. B<to> must point to a memory section large enough to hold the | ||
48 | message digest (which is smaller than B<RSA_size(rsa) - | ||
49 | 11>). B<padding> is the padding mode that was used to sign the data. | ||
50 | |||
51 | =head1 RETURN VALUES | ||
52 | |||
53 | RSA_private_encrypt() returns the size of the signature (i.e., | ||
54 | RSA_size(rsa)). RSA_public_decrypt() returns the size of the | ||
55 | recovered message digest. | ||
56 | |||
57 | On error, -1 is returned; the error codes can be | ||
58 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
59 | |||
60 | =head1 SEE ALSO | ||
61 | |||
62 | L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> | ||
63 | |||
64 | =head1 HISTORY | ||
65 | |||
66 | The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is | ||
67 | available since SSLeay 0.9.0. | ||
68 | |||
69 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_public_encrypt.pod b/src/lib/libcrypto/doc/RSA_public_encrypt.pod new file mode 100644 index 0000000000..910c4752b8 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_public_encrypt.pod | |||
@@ -0,0 +1,86 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_public_encrypt(int flen, unsigned char *from, | ||
12 | unsigned char *to, RSA *rsa, int padding); | ||
13 | |||
14 | int RSA_private_decrypt(int flen, unsigned char *from, | ||
15 | unsigned char *to, RSA *rsa, int padding); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a | ||
20 | session key) using the public key B<rsa> and stores the ciphertext in | ||
21 | B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. | ||
22 | |||
23 | B<padding> denotes one of the following modes: | ||
24 | |||
25 | =over 4 | ||
26 | |||
27 | =item RSA_PKCS1_PADDING | ||
28 | |||
29 | PKCS #1 v1.5 padding. This currently is the most widely used mode. | ||
30 | |||
31 | =item RSA_PKCS1_OAEP_PADDING | ||
32 | |||
33 | EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty | ||
34 | encoding parameter. This mode is recommended for all new applications. | ||
35 | |||
36 | =item RSA_SSLV23_PADDING | ||
37 | |||
38 | PKCS #1 v1.5 padding with an SSL-specific modification that denotes | ||
39 | that the server is SSL3 capable. | ||
40 | |||
41 | =item RSA_NO_PADDING | ||
42 | |||
43 | Raw RSA encryption. This mode should I<only> be used to implement | ||
44 | cryptographically sound padding modes in the application code. | ||
45 | Encrypting user data directly with RSA is insecure. | ||
46 | |||
47 | =back | ||
48 | |||
49 | B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 | ||
50 | based padding modes, and less than RSA_size(B<rsa>) - 21 for | ||
51 | RSA_PKCS1_OAEP_PADDING. The random number generator must be seeded | ||
52 | prior to calling RSA_public_encrypt(). | ||
53 | |||
54 | RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the | ||
55 | private key B<rsa> and stores the plaintext in B<to>. B<to> must point | ||
56 | to a memory section large enough to hold the decrypted data (which is | ||
57 | smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that | ||
58 | was used to encrypt the data. | ||
59 | |||
60 | =head1 RETURN VALUES | ||
61 | |||
62 | RSA_public_encrypt() returns the size of the encrypted data (i.e., | ||
63 | RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the | ||
64 | recovered plaintext. | ||
65 | |||
66 | On error, -1 is returned; the error codes can be | ||
67 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
68 | |||
69 | =head1 CONFORMING TO | ||
70 | |||
71 | SSL, PKCS #1 v2.0 | ||
72 | |||
73 | =head1 SEE ALSO | ||
74 | |||
75 | L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_size(3)|RSA_size(3)> | ||
76 | |||
77 | =head1 NOTES | ||
78 | |||
79 | The L<RSA_PKCS1_RSAref(3)|RSA_PKCS1_RSAref(3)> method supports only the RSA_PKCS1_PADDING mode. | ||
80 | |||
81 | =head1 HISTORY | ||
82 | |||
83 | The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is | ||
84 | available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. | ||
85 | |||
86 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod new file mode 100644 index 0000000000..deb1183a23 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_set_method.pod | |||
@@ -0,0 +1,153 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_set_default_method, RSA_get_default_method, RSA_set_method, | ||
6 | RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref, | ||
7 | RSA_PKCS1_null_method, RSA_flags, RSA_new_method - select RSA method | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/rsa.h> | ||
12 | |||
13 | void RSA_set_default_method(RSA_METHOD *meth); | ||
14 | |||
15 | RSA_METHOD *RSA_get_default_method(void); | ||
16 | |||
17 | RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); | ||
18 | |||
19 | RSA_METHOD *RSA_get_method(RSA *rsa); | ||
20 | |||
21 | RSA_METHOD *RSA_PKCS1_SSLeay(void); | ||
22 | |||
23 | RSA_METHOD *RSA_PKCS1_RSAref(void); | ||
24 | |||
25 | RSA_METHOD *RSA_null_method(void); | ||
26 | |||
27 | int RSA_flags(RSA *rsa); | ||
28 | |||
29 | RSA *RSA_new_method(RSA_METHOD *method); | ||
30 | |||
31 | =head1 DESCRIPTION | ||
32 | |||
33 | An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA | ||
34 | operations. By modifying the method, alternative implementations | ||
35 | such as hardware accelerators may be used. | ||
36 | |||
37 | Initially, the default is to use the OpenSSL internal implementation, | ||
38 | unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL> | ||
39 | options. RSA_PKCS1_SSLeay() returns a pointer to that method. | ||
40 | |||
41 | RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref | ||
42 | library. This is the default method in the C<rsaref> configuration; | ||
43 | the function is not available in other configurations. | ||
44 | RSA_null_method() returns a pointer to a method that does not support | ||
45 | the RSA transformation. It is the default if OpenSSL is compiled with | ||
46 | C<-DRSA_NULL>. These methods may be useful in the USA because of a | ||
47 | patent on the RSA cryptosystem. | ||
48 | |||
49 | RSA_set_default_method() makes B<meth> the default method for all B<RSA> | ||
50 | structures created later. | ||
51 | |||
52 | RSA_get_default_method() returns a pointer to the current default | ||
53 | method. | ||
54 | |||
55 | RSA_set_method() selects B<meth> for all operations using the key | ||
56 | B<rsa>. | ||
57 | |||
58 | RSA_get_method() returns a pointer to the method currently selected | ||
59 | for B<rsa>. | ||
60 | |||
61 | RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. | ||
62 | |||
63 | RSA_new_method() allocates and initializes an B<RSA> structure so that | ||
64 | B<method> will be used for the RSA operations. If B<method> is B<NULL>, | ||
65 | the default method is used. | ||
66 | |||
67 | =head1 THE RSA_METHOD STRUCTURE | ||
68 | |||
69 | typedef struct rsa_meth_st | ||
70 | { | ||
71 | /* name of the implementation */ | ||
72 | const char *name; | ||
73 | |||
74 | /* encrypt */ | ||
75 | int (*rsa_pub_enc)(int flen, unsigned char *from, | ||
76 | unsigned char *to, RSA *rsa, int padding); | ||
77 | |||
78 | /* verify arbitrary data */ | ||
79 | int (*rsa_pub_dec)(int flen, unsigned char *from, | ||
80 | unsigned char *to, RSA *rsa, int padding); | ||
81 | |||
82 | /* sign arbitrary data */ | ||
83 | int (*rsa_priv_enc)(int flen, unsigned char *from, | ||
84 | unsigned char *to, RSA *rsa, int padding); | ||
85 | |||
86 | /* decrypt */ | ||
87 | int (*rsa_priv_dec)(int flen, unsigned char *from, | ||
88 | unsigned char *to, RSA *rsa, int padding); | ||
89 | |||
90 | /* compute r0 = r0 ^ I mod rsa->n. May be NULL */ | ||
91 | int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); | ||
92 | |||
93 | /* compute r = a ^ p mod m. May be NULL */ | ||
94 | int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
95 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); | ||
96 | |||
97 | /* called at RSA_new */ | ||
98 | int (*init)(RSA *rsa); | ||
99 | |||
100 | /* called at RSA_free */ | ||
101 | int (*finish)(RSA *rsa); | ||
102 | |||
103 | /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key | ||
104 | * operations, even if p,q,dmp1,dmq1,iqmp | ||
105 | * are NULL | ||
106 | * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify | ||
107 | * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match | ||
108 | */ | ||
109 | int flags; | ||
110 | |||
111 | char *app_data; /* ?? */ | ||
112 | |||
113 | /* sign. For backward compatibility, this is used only | ||
114 | * if (flags & RSA_FLAG_SIGN_VER) | ||
115 | */ | ||
116 | int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, | ||
117 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
118 | |||
119 | /* verify. For backward compatibility, this is used only | ||
120 | * if (flags & RSA_FLAG_SIGN_VER) | ||
121 | */ | ||
122 | int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, | ||
123 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
124 | |||
125 | } RSA_METHOD; | ||
126 | |||
127 | =head1 RETURN VALUES | ||
128 | |||
129 | RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(), | ||
130 | RSA_get_default_method() and RSA_get_method() return pointers to the | ||
131 | respective B<RSA_METHOD>s. | ||
132 | |||
133 | RSA_set_default_method() returns no value. | ||
134 | |||
135 | RSA_set_method() returns a pointer to the B<RSA_METHOD> previously | ||
136 | associated with B<rsa>. | ||
137 | |||
138 | RSA_new_method() returns B<NULL> and sets an error code that can be | ||
139 | obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it | ||
140 | returns a pointer to the newly allocated structure. | ||
141 | |||
142 | =head1 SEE ALSO | ||
143 | |||
144 | L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> | ||
145 | |||
146 | =head1 HISTORY | ||
147 | |||
148 | RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. | ||
149 | RSA_get_default_method(), RSA_set_method() and RSA_get_method() as | ||
150 | well as the rsa_sign and rsa_verify components of RSA_METHOD were | ||
151 | added in OpenSSL 0.9.4. | ||
152 | |||
153 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_sign.pod b/src/lib/libcrypto/doc/RSA_sign.pod new file mode 100644 index 0000000000..f0bf6eea1b --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_sign.pod | |||
@@ -0,0 +1,62 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_sign, RSA_verify - RSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_sign(int type, unsigned char *m, unsigned int m_len, | ||
12 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
13 | |||
14 | int RSA_verify(int type, unsigned char *m, unsigned int m_len, | ||
15 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RSA_sign() signs the message digest B<m> of size B<m_len> using the | ||
20 | private key B<rsa> as specified in PKCS #1 v2.0. It stores the | ||
21 | signature in B<sigret> and the signature size in B<siglen>. B<sigret> | ||
22 | must point to RSA_size(B<rsa>) bytes of memory. | ||
23 | |||
24 | B<type> denotes the message digest algorithm that was used to generate | ||
25 | B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; | ||
26 | see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>, | ||
27 | an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding | ||
28 | and no algorithm identifier) is created. | ||
29 | |||
30 | RSA_verify() verifies that the signature B<sigbuf> of size B<siglen> | ||
31 | matches a given message digest B<m> of size B<m_len>. B<type> denotes | ||
32 | the message digest algorithm that was used to generate the signature. | ||
33 | B<rsa> is the signer's public key. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 | ||
38 | on successful verification, 0 otherwise. | ||
39 | |||
40 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
41 | |||
42 | =head1 BUGS | ||
43 | |||
44 | Certain signatures with an improper algorithm identifier are accepted | ||
45 | for compatibility with SSLeay 0.4.5 :-) | ||
46 | |||
47 | =head1 CONFORMING TO | ||
48 | |||
49 | SSL, PKCS #1 v2.0 | ||
50 | |||
51 | =head1 SEE ALSO | ||
52 | |||
53 | L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rsa(3)|rsa(3)>, | ||
54 | L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, | ||
55 | L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> | ||
56 | |||
57 | =head1 HISTORY | ||
58 | |||
59 | RSA_sign() and RSA_verify() are available in all versions of SSLeay | ||
60 | and OpenSSL. | ||
61 | |||
62 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod b/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod new file mode 100644 index 0000000000..df9ceb339a --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod | |||
@@ -0,0 +1,59 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
12 | unsigned int m_len, unsigned char *sigret, unsigned int *siglen, | ||
13 | RSA *rsa); | ||
14 | |||
15 | int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
16 | unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, | ||
17 | RSA *rsa); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size | ||
22 | B<m_len> using the private key B<rsa> represented in DER using PKCS #1 | ||
23 | padding. It stores the signature in B<sigret> and the signature size | ||
24 | in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of | ||
25 | memory. | ||
26 | |||
27 | B<dummy> is ignored. | ||
28 | |||
29 | The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING(). | ||
30 | |||
31 | RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf> | ||
32 | of size B<siglen> is the DER representation of a given octet string | ||
33 | B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's | ||
34 | public key. | ||
35 | |||
36 | =head1 RETURN VALUES | ||
37 | |||
38 | RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. | ||
39 | RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 | ||
40 | otherwise. | ||
41 | |||
42 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
43 | |||
44 | =head1 BUGS | ||
45 | |||
46 | These functions serve no recognizable purpose. | ||
47 | |||
48 | =head1 SEE ALSO | ||
49 | |||
50 | L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rand(3)|rand(3)>, | ||
51 | L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, | ||
52 | L<RSA_verify(3)|RSA_verify(3)> | ||
53 | |||
54 | =head1 HISTORY | ||
55 | |||
56 | RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were | ||
57 | added in SSLeay 0.8. | ||
58 | |||
59 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_size.pod b/src/lib/libcrypto/doc/RSA_size.pod new file mode 100644 index 0000000000..b36b4d58d5 --- /dev/null +++ b/src/lib/libcrypto/doc/RSA_size.pod | |||
@@ -0,0 +1,33 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_size - get RSA modulus size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_size(RSA *rsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the RSA modulus size in bytes. It can be used to | ||
16 | determine how much memory must be allocated for an RSA encrypted | ||
17 | value. | ||
18 | |||
19 | B<rsa-E<gt>n> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<rsa(3)|rsa(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | RSA_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/bn.pod b/src/lib/libcrypto/doc/bn.pod new file mode 100644 index 0000000000..1504a1c92d --- /dev/null +++ b/src/lib/libcrypto/doc/bn.pod | |||
@@ -0,0 +1,148 @@ | |||
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 | int BN_num_bytes(const BIGNUM *a); | ||
25 | int BN_num_bits(const BIGNUM *a); | ||
26 | int BN_num_bits_word(BN_ULONG w); | ||
27 | |||
28 | int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
29 | int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); | ||
30 | int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
31 | int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, | ||
32 | BN_CTX *ctx); | ||
33 | int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); | ||
34 | int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
35 | int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
36 | BN_CTX *ctx); | ||
37 | int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); | ||
38 | int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
39 | const BIGNUM *m, BN_CTX *ctx); | ||
40 | int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
41 | |||
42 | int BN_add_word(BIGNUM *a, BN_ULONG w); | ||
43 | int BN_sub_word(BIGNUM *a, BN_ULONG w); | ||
44 | int BN_mul_word(BIGNUM *a, BN_ULONG w); | ||
45 | BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); | ||
46 | BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); | ||
47 | |||
48 | int BN_cmp(BIGNUM *a, BIGNUM *b); | ||
49 | int BN_ucmp(BIGNUM *a, BIGNUM *b); | ||
50 | int BN_is_zero(BIGNUM *a); | ||
51 | int BN_is_one(BIGNUM *a); | ||
52 | int BN_is_word(BIGNUM *a, BN_ULONG w); | ||
53 | int BN_is_odd(BIGNUM *a); | ||
54 | |||
55 | int BN_zero(BIGNUM *a); | ||
56 | int BN_one(BIGNUM *a); | ||
57 | BIGNUM *BN_value_one(void); | ||
58 | int BN_set_word(BIGNUM *a, unsigned long w); | ||
59 | unsigned long BN_get_word(BIGNUM *a); | ||
60 | |||
61 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
62 | int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
63 | |||
64 | BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, | ||
65 | BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); | ||
66 | int BN_is_prime(const BIGNUM *p, int nchecks, | ||
67 | void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); | ||
68 | |||
69 | int BN_set_bit(BIGNUM *a, int n); | ||
70 | int BN_clear_bit(BIGNUM *a, int n); | ||
71 | int BN_is_bit_set(const BIGNUM *a, int n); | ||
72 | int BN_mask_bits(BIGNUM *a, int n); | ||
73 | int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); | ||
74 | int BN_lshift1(BIGNUM *r, BIGNUM *a); | ||
75 | int BN_rshift(BIGNUM *r, BIGNUM *a, int n); | ||
76 | int BN_rshift1(BIGNUM *r, BIGNUM *a); | ||
77 | |||
78 | int BN_bn2bin(const BIGNUM *a, unsigned char *to); | ||
79 | BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); | ||
80 | char *BN_bn2hex(const BIGNUM *a); | ||
81 | char *BN_bn2dec(const BIGNUM *a); | ||
82 | int BN_hex2bn(BIGNUM **a, const char *str); | ||
83 | int BN_dec2bn(BIGNUM **a, const char *str); | ||
84 | int BN_print(BIO *fp, const BIGNUM *a); | ||
85 | int BN_print_fp(FILE *fp, const BIGNUM *a); | ||
86 | int BN_bn2mpi(const BIGNUM *a, unsigned char *to); | ||
87 | BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); | ||
88 | |||
89 | BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, | ||
90 | BN_CTX *ctx); | ||
91 | |||
92 | BN_RECP_CTX *BN_RECP_CTX_new(void); | ||
93 | void BN_RECP_CTX_init(BN_RECP_CTX *recp); | ||
94 | void BN_RECP_CTX_free(BN_RECP_CTX *recp); | ||
95 | int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); | ||
96 | int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
97 | BN_RECP_CTX *recp, BN_CTX *ctx); | ||
98 | |||
99 | BN_MONT_CTX *BN_MONT_CTX_new(void); | ||
100 | void BN_MONT_CTX_init(BN_MONT_CTX *ctx); | ||
101 | void BN_MONT_CTX_free(BN_MONT_CTX *mont); | ||
102 | int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); | ||
103 | BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); | ||
104 | int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
105 | BN_MONT_CTX *mont, BN_CTX *ctx); | ||
106 | int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
107 | BN_CTX *ctx); | ||
108 | int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
109 | BN_CTX *ctx); | ||
110 | |||
111 | |||
112 | =head1 DESCRIPTION | ||
113 | |||
114 | This library performs arithmetic operations on integers of arbitrary | ||
115 | size. It was written for use in public key cryptography, such as RSA | ||
116 | and Diffie-Hellman. | ||
117 | |||
118 | It uses dynamic memory allocation for storing its data structures. | ||
119 | That means that there is no limit on the size of the numbers | ||
120 | manipulated by these functions, but return values must always be | ||
121 | checked in case a memory allocation error has occurred. | ||
122 | |||
123 | The basic object in this library is a B<BIGNUM>. It is used to hold a | ||
124 | single large integer. This type should be considered opaque and fields | ||
125 | should not be modified or accessed directly. | ||
126 | |||
127 | The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; | ||
128 | L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. | ||
129 | Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> | ||
130 | describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of | ||
131 | random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime | ||
132 | numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion | ||
133 | of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. | ||
134 | |||
135 | =head1 SEE ALSO | ||
136 | |||
137 | L<bn_internal(3)|bn_internal(3)>, | ||
138 | L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, | ||
139 | L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, | ||
140 | L<BN_copy(3)|BN_copy(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, | ||
141 | L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, | ||
142 | L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, | ||
143 | L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, | ||
144 | L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, | ||
145 | L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, | ||
146 | L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> | ||
147 | |||
148 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_DHparams.pod b/src/lib/libcrypto/doc/d2i_DHparams.pod new file mode 100644 index 0000000000..a6d1743d39 --- /dev/null +++ b/src/lib/libcrypto/doc/d2i_DHparams.pod | |||
@@ -0,0 +1,30 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_DHparams, i2d_DHparams - ... | ||
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 | ... | ||
17 | |||
18 | =head1 RETURN VALUES | ||
19 | |||
20 | ... | ||
21 | |||
22 | =head1 SEE ALSO | ||
23 | |||
24 | ... | ||
25 | |||
26 | =head1 HISTORY | ||
27 | |||
28 | ... | ||
29 | |||
30 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod new file mode 100644 index 0000000000..ff4d0d57db --- /dev/null +++ b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod | |||
@@ -0,0 +1,39 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Netscape_RSA, d2i_Netscape_RSA - ... | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length); | ||
12 | |||
13 | int i2d_RSAPublicKey(RSA *a, unsigned char **pp); | ||
14 | |||
15 | RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length); | ||
16 | |||
17 | int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); | ||
18 | |||
19 | int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); | ||
20 | |||
21 | RSA * d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); | ||
22 | |||
23 | =head1 DESCRIPTION | ||
24 | |||
25 | ... | ||
26 | |||
27 | =head1 RETURN VALUES | ||
28 | |||
29 | ... | ||
30 | |||
31 | =head1 SEE ALSO | ||
32 | |||
33 | ... | ||
34 | |||
35 | =head1 HISTORY | ||
36 | |||
37 | ... | ||
38 | |||
39 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dh.pod b/src/lib/libcrypto/doc/dh.pod new file mode 100644 index 0000000000..0a9b7c03a2 --- /dev/null +++ b/src/lib/libcrypto/doc/dh.pod | |||
@@ -0,0 +1,68 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dh - Diffie-Hellman key agreement | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH * DH_new(void); | ||
12 | void DH_free(DH *dh); | ||
13 | |||
14 | int DH_size(DH *dh); | ||
15 | |||
16 | DH * DH_generate_parameters(int prime_len, int generator, | ||
17 | void (*callback)(int, int, void *), void *cb_arg); | ||
18 | int DH_check(DH *dh, int *codes); | ||
19 | |||
20 | int DH_generate_key(DH *dh); | ||
21 | int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
22 | |||
23 | void DH_set_default_method(DH_METHOD *meth); | ||
24 | DH_METHOD *DH_get_default_method(void); | ||
25 | DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); | ||
26 | DH *DH_new_method(DH_METHOD *meth); | ||
27 | DH_METHOD *DH_OpenSSL(void); | ||
28 | |||
29 | int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
30 | int (*dup_func)(), void (*free_func)()); | ||
31 | int DH_set_ex_data(DH *d, int idx, char *arg); | ||
32 | char *DH_get_ex_data(DH *d, int idx); | ||
33 | |||
34 | DH * d2i_DHparams(DH **a, unsigned char **pp, long length); | ||
35 | int i2d_DHparams(DH *a, unsigned char **pp); | ||
36 | |||
37 | int DHparams_print_fp(FILE *fp, DH *x); | ||
38 | int DHparams_print(BIO *bp, DH *x); | ||
39 | |||
40 | =head1 DESCRIPTION | ||
41 | |||
42 | These functions implement the Diffie-Hellman key agreement protocol. | ||
43 | The generation of shared DH parameters is described in | ||
44 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how | ||
45 | to perform a key agreement. | ||
46 | |||
47 | The B<DH> structure consists of several BIGNUM components. | ||
48 | |||
49 | struct | ||
50 | { | ||
51 | BIGNUM *p; // prime number (shared) | ||
52 | BIGNUM *g; // generator of Z_p (shared) | ||
53 | BIGNUM *priv_key; // private DH value x | ||
54 | BIGNUM *pub_key; // public DH value g^x | ||
55 | // ... | ||
56 | }; | ||
57 | DH | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, | ||
62 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<DH_set_method(3)|DH_set_method(3)>, | ||
63 | L<DH_new(3)|DH_new(3)>, L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, | ||
64 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>, | ||
65 | L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, | ||
66 | L<RSA_print(3)|RSA_print(3)> | ||
67 | |||
68 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dsa.pod b/src/lib/libcrypto/doc/dsa.pod new file mode 100644 index 0000000000..2c09244899 --- /dev/null +++ b/src/lib/libcrypto/doc/dsa.pod | |||
@@ -0,0 +1,104 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dsa - Digital Signature Algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA * DSA_new(void); | ||
12 | void DSA_free(DSA *dsa); | ||
13 | |||
14 | int DSA_size(DSA *dsa); | ||
15 | |||
16 | DSA * DSA_generate_parameters(int bits, unsigned char *seed, | ||
17 | int seed_len, int *counter_ret, unsigned long *h_ret, | ||
18 | void (*callback)(int, int, void *), void *cb_arg); | ||
19 | |||
20 | DH * DSA_dup_DH(DSA *r); | ||
21 | |||
22 | int DSA_generate_key(DSA *dsa); | ||
23 | |||
24 | int DSA_sign(int dummy, const unsigned char *dgst, int len, | ||
25 | unsigned char *sigret, unsigned int *siglen, DSA *dsa); | ||
26 | int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, | ||
27 | BIGNUM **rp); | ||
28 | int DSA_verify(int dummy, const unsigned char *dgst, int len, | ||
29 | unsigned char *sigbuf, int siglen, DSA *dsa); | ||
30 | |||
31 | void DSA_set_default_method(DSA_METHOD *meth); | ||
32 | DSA_METHOD *DSA_get_default_method(void); | ||
33 | DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); | ||
34 | DSA *DSA_new_method(DSA_METHOD *meth); | ||
35 | DSA_METHOD *DSA_OpenSSL(void); | ||
36 | |||
37 | int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
38 | int (*dup_func)(), void (*free_func)()); | ||
39 | int DSA_set_ex_data(DSA *d, int idx, char *arg); | ||
40 | char *DSA_get_ex_data(DSA *d, int idx); | ||
41 | |||
42 | DSA_SIG *DSA_SIG_new(void); | ||
43 | void DSA_SIG_free(DSA_SIG *a); | ||
44 | int i2d_DSA_SIG(DSA_SIG *a, unsigned char **pp); | ||
45 | DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); | ||
46 | |||
47 | DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); | ||
48 | int DSA_do_verify(const unsigned char *dgst, int dgst_len, | ||
49 | DSA_SIG *sig, DSA *dsa); | ||
50 | |||
51 | DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); | ||
52 | DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); | ||
53 | DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); | ||
54 | int i2d_DSAPublicKey(DSA *a, unsigned char **pp); | ||
55 | int i2d_DSAPrivateKey(DSA *a, unsigned char **pp); | ||
56 | int i2d_DSAparams(DSA *a,unsigned char **pp); | ||
57 | |||
58 | int DSAparams_print(BIO *bp, DSA *x); | ||
59 | int DSAparams_print_fp(FILE *fp, DSA *x); | ||
60 | int DSA_print(BIO *bp, DSA *x, int off); | ||
61 | int DSA_print_fp(FILE *bp, DSA *x, int off); | ||
62 | |||
63 | =head1 DESCRIPTION | ||
64 | |||
65 | These functions implement the Digital Signature Algorithm (DSA). The | ||
66 | generation of shared DSA parameters is described in | ||
67 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; | ||
68 | L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to | ||
69 | generate a signature key. Signature generation and verification are | ||
70 | described in L<DSA_sign(3)|DSA_sign(3)>. | ||
71 | |||
72 | The B<DSA> structure consists of several BIGNUM components. | ||
73 | |||
74 | struct | ||
75 | { | ||
76 | BIGNUM *p; // prime number (public) | ||
77 | BIGNUM *q; // 160-bit subprime, q | p-1 (public) | ||
78 | BIGNUM *g; // generator of subgroup (public) | ||
79 | BIGNUM *priv_key; // private key x | ||
80 | BIGNUM *pub_key; // public key y = g^x | ||
81 | // ... | ||
82 | } | ||
83 | DSA; | ||
84 | |||
85 | In public keys, B<priv_key> is NULL. | ||
86 | |||
87 | =head1 CONFORMING TO | ||
88 | |||
89 | US Federal Information Processing Standard FIPS 186 (Digital Signature | ||
90 | Standard, DSS), ANSI X9.30 | ||
91 | |||
92 | =head1 SEE ALSO | ||
93 | |||
94 | L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
95 | L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<DSA_new(3)|DSA_new(3)>, | ||
96 | L<DSA_size(3)|DSA_size(3)>, | ||
97 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, | ||
98 | L<DSA_dup_DH(3)|DSA_dup_DH(3)>, | ||
99 | L<DSA_generate_key(3)|DSA_generate_key(3)>, | ||
100 | L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, | ||
101 | L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, | ||
102 | L<RSA_print(3)|RSA_print(3)> | ||
103 | |||
104 | =cut | ||
diff --git a/src/lib/libcrypto/doc/lh_stats.pod b/src/lib/libcrypto/doc/lh_stats.pod new file mode 100644 index 0000000000..3eeaa72e52 --- /dev/null +++ b/src/lib/libcrypto/doc/lh_stats.pod | |||
@@ -0,0 +1,60 @@ | |||
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<lhash(3)|lhash(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 | ||
diff --git a/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod new file mode 100644 index 0000000000..0486c044a6 --- /dev/null +++ b/src/lib/libcrypto/doc/rsa.pod | |||
@@ -0,0 +1,115 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | rsa - RSA public key cryptosystem | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | RSA * RSA_new(void); | ||
12 | void RSA_free(RSA *rsa); | ||
13 | |||
14 | int RSA_public_encrypt(int flen, unsigned char *from, | ||
15 | unsigned char *to, RSA *rsa, int padding); | ||
16 | int RSA_private_decrypt(int flen, unsigned char *from, | ||
17 | unsigned char *to, RSA *rsa, int padding); | ||
18 | |||
19 | int RSA_sign(int type, unsigned char *m, unsigned int m_len, | ||
20 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
21 | int RSA_verify(int type, unsigned char *m, unsigned int m_len, | ||
22 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
23 | |||
24 | int RSA_size(RSA *rsa); | ||
25 | |||
26 | RSA *RSA_generate_key(int num, unsigned long e, | ||
27 | void (*callback)(int,int,void *), void *cb_arg); | ||
28 | |||
29 | int RSA_check_key(RSA *rsa); | ||
30 | |||
31 | int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); | ||
32 | void RSA_blinding_off(RSA *rsa); | ||
33 | |||
34 | void RSA_set_default_method(RSA_METHOD *meth); | ||
35 | RSA_METHOD *RSA_get_default_method(void); | ||
36 | RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); | ||
37 | RSA_METHOD *RSA_get_method(RSA *rsa); | ||
38 | RSA_METHOD *RSA_PKCS1_SSLeay(void); | ||
39 | RSA_METHOD *RSA_PKCS1_RSAref(void); | ||
40 | RSA_METHOD *RSA_null_method(void); | ||
41 | int RSA_flags(RSA *rsa); | ||
42 | RSA *RSA_new_method(RSA_METHOD *method); | ||
43 | |||
44 | int RSA_print(BIO *bp, RSA *x, int offset); | ||
45 | int RSA_print_fp(FILE *fp, RSA *x, int offset); | ||
46 | |||
47 | int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
48 | int (*dup_func)(), void (*free_func)()); | ||
49 | int RSA_set_ex_data(RSA *r,int idx,char *arg); | ||
50 | char *RSA_get_ex_data(RSA *r, int idx); | ||
51 | |||
52 | int RSA_private_encrypt(int flen, unsigned char *from, | ||
53 | unsigned char *to, RSA *rsa,int padding); | ||
54 | int RSA_public_decrypt(int flen, unsigned char *from, | ||
55 | unsigned char *to, RSA *rsa,int padding); | ||
56 | |||
57 | int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
58 | unsigned int m_len, unsigned char *sigret, unsigned int *siglen, | ||
59 | RSA *rsa); | ||
60 | int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
61 | unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, | ||
62 | RSA *rsa); | ||
63 | |||
64 | =head1 DESCRIPTION | ||
65 | |||
66 | These functions implement RSA public key encryption and signatures | ||
67 | as defined in PKCS #1 v2.0 [RFC 2437]. | ||
68 | |||
69 | The B<RSA> structure consists of several BIGNUM components. It can | ||
70 | contain public as well as private RSA keys: | ||
71 | |||
72 | struct | ||
73 | { | ||
74 | BIGNUM *n; // public modulus | ||
75 | BIGNUM *e; // public exponent | ||
76 | BIGNUM *d; // private exponent | ||
77 | BIGNUM *p; // secret prime factor | ||
78 | BIGNUM *q; // secret prime factor | ||
79 | BIGNUM *dmp1; // d mod (p-1) | ||
80 | BIGNUM *dmq1; // d mod (q-1) | ||
81 | BIGNUM *iqmp; // q^-1 mod p | ||
82 | // ... | ||
83 | }; | ||
84 | RSA | ||
85 | |||
86 | In public keys, the private exponent and the related secret values are | ||
87 | B<NULL>. | ||
88 | |||
89 | B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private keys, but the | ||
90 | RSA operations are much faster when these values are available. | ||
91 | |||
92 | =head1 CONFORMING TO | ||
93 | |||
94 | SSL, PKCS #1 v2.0 | ||
95 | |||
96 | =head1 PATENTS | ||
97 | |||
98 | RSA is covered by a US patent which expires in September 2000. | ||
99 | |||
100 | =head1 SEE ALSO | ||
101 | |||
102 | L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, | ||
103 | L<rand(3)|rand(3)>, L<RSA_new(3)|RSA_new(3)>, | ||
104 | L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, | ||
105 | L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, | ||
106 | L<RSA_generate_key(3)|RSA_generate_key(3)>, | ||
107 | L<RSA_check_key(3)|RSA_check_key(3)>, | ||
108 | L<RSA_blinding_on(3)|RSA_blinding_on(3)>, | ||
109 | L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, | ||
110 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, | ||
111 | L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, | ||
112 | L<RSA_sign_ASN_OCTET_STRING(3)|RSA_sign_ASN_OCTET_STRING(3)>, | ||
113 | L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> | ||
114 | |||
115 | =cut | ||