summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDr. Stephen Henson <steve@openssl.org>2000-01-30 01:39:40 +0000
committerDr. Stephen Henson <steve@openssl.org>2000-01-30 01:39:40 +0000
commit15701211b57b63f1f91a9c3781ea91c019b1dc1d (patch)
tree86796032e60d1f140a5429da70cf3571d2469c17
parent1e264ff3251d63c67e2778f4d58228579173efbc (diff)
Update docs.
-rw-r--r--doc/crypto/BN_CTX_new.pod10
-rw-r--r--doc/crypto/BN_zero.pod3
-rw-r--r--doc/crypto/CRYPTO_set_ex_data.pod51
-rw-r--r--doc/crypto/RSA_get_ex_new_index.pod4
-rw-r--r--doc/crypto/bn.pod10
5 files changed, 67 insertions, 11 deletions
diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod
index 45c70fd407..37a188e3c3 100644
--- a/doc/crypto/BN_CTX_new.pod
+++ b/doc/crypto/BN_CTX_new.pod
@@ -16,12 +16,12 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
=head1 DESCRIPTION
-A B<BN_CTX> is a structure that holds temporary variables used by
-library functions. Thus, it can be avoided to create and destroy
-the temporary B<BIGNUM> objects whenever a library function is
-called.
+A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
+library functions. Since dynamic memory allocation to create B<BIGNUM>s
+is rather expensive when used in conjunction with repeated subroutine
+calls, the B<BN_CTX> structure is used.
-BN_CTX_new() allocated and initializes a B<BN_CTX>
+BN_CTX_new() allocates and initializes a B<BN_CTX>
structure. BN_CTX_init() initializes an existing uninitialized
B<BN_CTX>.
diff --git a/doc/crypto/BN_zero.pod b/doc/crypto/BN_zero.pod
index 43b6337bae..165fd9a228 100644
--- a/doc/crypto/BN_zero.pod
+++ b/doc/crypto/BN_zero.pod
@@ -39,6 +39,9 @@ BN_value_one() returns the constant.
Someone might change the constant.
+If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
+unsigned long but this value is also returned on error.
+
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
diff --git a/doc/crypto/CRYPTO_set_ex_data.pod b/doc/crypto/CRYPTO_set_ex_data.pod
new file mode 100644
index 0000000000..1bd5bed67d
--- /dev/null
+++ b/doc/crypto/CRYPTO_set_ex_data.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
+
+ void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
+
+=head1 DESCRIPTION
+
+Several OpenSSL structures can have application specific data attached to them.
+These functions are used internally by OpenSSL to manipulate application
+specific data attached to a specific structure.
+
+These functions should only be used by applications to manipulate
+B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and
+B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example.
+
+B<CRYPTO_set_ex_data()> is used to set application specific data, the data is
+supplied in the B<arg> parameter and its precise meaning is up to the
+application.
+
+B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data
+is returned to the application, this will be the same value as supplied to
+a previous B<CRYPTO_set_ex_data()> call.
+
+=head1 RETURN VALUES
+
+B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure.
+
+B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also
+be valid application data but currently it can only fail if given an invalid B<idx>
+parameter.
+
+On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>,
+L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>
+
+=head1 HISTORY
+
+CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/RSA_get_ex_new_index.pod b/doc/crypto/RSA_get_ex_new_index.pod
index d0267a2ea1..920dc76325 100644
--- a/doc/crypto/RSA_get_ex_new_index.pod
+++ b/doc/crypto/RSA_get_ex_new_index.pod
@@ -71,7 +71,7 @@ B<new_func()> and B<free_func()> take the same parameters. B<parent> is a
pointer to the parent RSA structure. B<ptr> is a the application specific data
(this wont be of much use in B<new_func()>. B<ad> is a pointer to the
B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions
-B<CRYPTO_get_ex_data()> and B<CRYPTO_get_ex_data()> can be called to manipulate
+B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate
it. The B<idx> parameter is the index: this will be the same value returned by
B<RSA_get_ex_new_index()> when the functions were initially registered. Finally
the B<argl> and B<argp> parameters are the values originally passed to the same
@@ -112,7 +112,7 @@ present in the parent RSA structure when it is called.
=head1 SEE ALSO
-L<rsa(3)|rsa(3)>
+L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
=head1 HISTORY
diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod
index 3d4840f095..823561fa8d 100644
--- a/doc/crypto/bn.pod
+++ b/doc/crypto/bn.pod
@@ -144,14 +144,14 @@ The following description is based on the SSLeay documentation:
int neg;
} BIGNUM;
-The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s.
-A B<BN_ULONG> can be either 16, 32 or 64 bits in size, depending on
-the 'number of bits' specified in bn.h.
+The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s,
+least significant first. A B<BN_ULONG> can be either 16, 32 or 64 bits
+in size, depending on the 'number of bits' specified in bn.h.
B<max> is the size of the B<d> array that has been allocated. B<top>
is the 'last' entry being used, so for a value of 4, bn.d[0]=4 and
bn.top=1. B<neg> is 1 if the number is negative. When a BIGNUM is
-'0', the B<d> field can be NULL and B<top> == 0. Various routines in
+'0', the B<d> field can be NULL and B<top> == 0. Various routines in
this library require the use of temporary B<BIGNUM> variables during
their execution. Since dynamic memory allocation to create B<BIGNUM>s
is rather expensive when used in conjunction with repeated subroutine
@@ -166,6 +166,8 @@ temporary B<BIGNUM>s any publicly exported function will use.
BIGNUM *bn[BN_CTX_NUM]; /* The variables */
} BN_CTX;
+B<tos> is the index of the first unused B<BIGNUM> in the B<bn> array.
+
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,