From 90c573eba184fe31184d14ce10367f810fa1d417 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 2 Nov 2016 11:57:56 +0000 Subject: convert DSA and EC manuals from pod to mdoc --- src/lib/libcrypto/doc/DSA_SIG_new.pod | 38 ----- src/lib/libcrypto/doc/DSA_do_sign.pod | 47 ------ src/lib/libcrypto/doc/DSA_dup_DH.pod | 36 ----- src/lib/libcrypto/doc/DSA_generate_key.pod | 32 ---- src/lib/libcrypto/doc/DSA_generate_parameters.pod | 122 --------------- src/lib/libcrypto/doc/DSA_get_ex_new_index.pod | 37 ----- src/lib/libcrypto/doc/DSA_new.pod | 40 ----- src/lib/libcrypto/doc/DSA_set_method.pod | 143 ------------------ src/lib/libcrypto/doc/DSA_sign.pod | 63 -------- src/lib/libcrypto/doc/DSA_size.pod | 33 ---- src/lib/libcrypto/doc/EC_GFp_simple_method.pod | 60 -------- src/lib/libcrypto/doc/EC_GROUP_copy.pod | 174 ---------------------- src/lib/libcrypto/doc/EC_GROUP_new.pod | 95 ------------ src/lib/libcrypto/doc/EC_KEY_new.pod | 115 -------------- src/lib/libcrypto/doc/EC_POINT_add.pod | 72 --------- src/lib/libcrypto/doc/EC_POINT_new.pod | 123 --------------- 16 files changed, 1230 deletions(-) delete mode 100644 src/lib/libcrypto/doc/DSA_SIG_new.pod delete mode 100644 src/lib/libcrypto/doc/DSA_do_sign.pod delete mode 100644 src/lib/libcrypto/doc/DSA_dup_DH.pod delete mode 100644 src/lib/libcrypto/doc/DSA_generate_key.pod delete mode 100644 src/lib/libcrypto/doc/DSA_generate_parameters.pod delete mode 100644 src/lib/libcrypto/doc/DSA_get_ex_new_index.pod delete mode 100644 src/lib/libcrypto/doc/DSA_new.pod delete mode 100644 src/lib/libcrypto/doc/DSA_set_method.pod delete mode 100644 src/lib/libcrypto/doc/DSA_sign.pod delete mode 100644 src/lib/libcrypto/doc/DSA_size.pod delete mode 100644 src/lib/libcrypto/doc/EC_GFp_simple_method.pod delete mode 100644 src/lib/libcrypto/doc/EC_GROUP_copy.pod delete mode 100644 src/lib/libcrypto/doc/EC_GROUP_new.pod delete mode 100644 src/lib/libcrypto/doc/EC_KEY_new.pod delete mode 100644 src/lib/libcrypto/doc/EC_POINT_add.pod delete mode 100644 src/lib/libcrypto/doc/EC_POINT_new.pod (limited to 'src/lib/libcrypto/doc') diff --git a/src/lib/libcrypto/doc/DSA_SIG_new.pod b/src/lib/libcrypto/doc/DSA_SIG_new.pod deleted file mode 100644 index 77aa649db0..0000000000 --- a/src/lib/libcrypto/doc/DSA_SIG_new.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects - -=head1 SYNOPSIS - - #include - - DSA_SIG *DSA_SIG_new(void); - - void DSA_SIG_free(DSA_SIG *a); - -=head1 DESCRIPTION - -DSA_SIG_new() allocates and initializes a B structure. - -DSA_SIG_free() frees the B structure and its components. The -values are erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, DSA_SIG_new() returns B and sets an -error code that can be obtained by -L. Otherwise it returns a pointer -to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L - -=head1 HISTORY - -DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_do_sign.pod b/src/lib/libcrypto/doc/DSA_do_sign.pod deleted file mode 100644 index 5dfc733b20..0000000000 --- a/src/lib/libcrypto/doc/DSA_do_sign.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -DSA_do_sign, DSA_do_verify - raw DSA signature operations - -=head1 SYNOPSIS - - #include - - DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); - - int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - -=head1 DESCRIPTION - -DSA_do_sign() computes a digital signature on the B byte message -digest B using the private key B and returns it in a -newly allocated B structure. - -L may be used to precompute part -of the signing operation in case signature generation is -time-critical. - -DSA_do_verify() verifies that the signature B matches a given -message digest B of size B. B is the signer's public -key. - -=head1 RETURN VALUES - -DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() -returns 1 for a valid signature, 0 for an incorrect signature and -1 -on error. The error codes can be obtained by -L. - -=head1 SEE ALSO - -L, L, L, -L, -L - -=head1 HISTORY - -DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod deleted file mode 100644 index 7f6f0d1115..0000000000 --- a/src/lib/libcrypto/doc/DSA_dup_DH.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DSA_dup_DH - create a DH structure out of DSA structure - -=head1 SYNOPSIS - - #include - - DH * DSA_dup_DH(const DSA *r); - -=head1 DESCRIPTION - -DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q -is lost during that conversion, but the resulting DH parameters -contain its length. - -=head1 RETURN VALUE - -DSA_dup_DH() returns the new B structure, and NULL on error. The -error codes can be obtained by L. - -=head1 NOTE - -Be careful to avoid small subgroup attacks when using this. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -DSA_dup_DH() was added in OpenSSL 0.9.4. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_generate_key.pod b/src/lib/libcrypto/doc/DSA_generate_key.pod deleted file mode 100644 index 069a05767c..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_key.pod +++ /dev/null @@ -1,32 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_key - generate DSA key pair - -=head1 SYNOPSIS - - #include - - int DSA_generate_key(DSA *a); - -=head1 DESCRIPTION - -DSA_generate_key() expects B to contain DSA parameters. It generates -a new key pair and stores it in Bpub_key> and Bpriv_key>. - -=head1 RETURN VALUE - -DSA_generate_key() returns 1 on success, 0 otherwise. -The error codes can be obtained by L. - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DSA_generate_key() is available since SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_generate_parameters.pod b/src/lib/libcrypto/doc/DSA_generate_parameters.pod deleted file mode 100644 index 698b555a0e..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_parameters.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters - -=head1 SYNOPSIS - - #include - - int DSA_generate_parameters_ex(DSA *dsa, int bits, - const unsigned char *seed,int seed_len, - int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); - -Deprecated: - - DSA *DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - -=head1 DESCRIPTION - -DSA_generate_parameters_ex() generates primes p and q and a generator g -for use in the DSA and stores the result in B. - -B is the length of the prime to be generated; the DSS allows a -maximum of 1024 bits. - -If B is B or B E 20, the primes will be -generated at random. Otherwise, the seed is used to generate -them. If the given seed does not yield a prime q, a new random -seed is chosen and placed at B. - -DSA_generate_parameters_ex() places the iteration count in -*B and a counter used for finding a generator in -*B, unless these are B. - -A callback function may be used to provide feedback about the progress -of the key generation. If B is not B, it will be -called as shown below. For information on the BN_GENCB structure and the -BN_GENCB_call function discussed below, refer to -L. - -=over 4 - -=item * - -When a candidate for q is generated, B is called -(m is 0 for the first candidate). - -=item * - -When a candidate for q has passed a test by trial division, -B is called. -While a candidate for q is tested by Miller-Rabin primality tests, -B is called in the outer loop -(once for each witness that confirms that the candidate may be prime); -i is the loop counter (starting at 0). - -=item * - -When a prime q has been found, B and -B are called. - -=item * - -Before a candidate for p (other than the first) is generated and tested, -B is called. - -=item * - -When a candidate for p has passed the test by trial division, -B is called. -While it is tested by the Miller-Rabin primality test, -B is called in the outer loop -(once for each witness that confirms that the candidate may be prime). -i is the loop counter (starting at 0). - -=item * - -When p has been found, B is called. - -=item * - -When the generator has been found, B is called. - -=back - -DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B parameter is passed and -instead a newly allocated B structure is returned. Additionally "old -style" callbacks are used instead of the newer BN_GENCB based approach. -Refer to L for further information. - -=head1 RETURN VALUE - -DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. - -DSA_generate_parameters() returns a pointer to the DSA structure, or -B if the parameter generation fails. - -The error codes can be obtained by L. - -=head1 BUGS - -Seed lengths E 20 are not supported. - -=head1 SEE ALSO - -L, L, L, -L, L - -=head1 HISTORY - -DSA_generate_parameters() appeared in SSLeay 0.8. The B -argument was added in SSLeay 0.9.0. -In versions up to OpenSSL 0.9.4, B was called -in the inner loop of the Miller-Rabin test whenever it reached the -squaring step (the parameters to B did not reveal how many -witnesses had been tested); since OpenSSL 0.9.5, B -is called as in BN_is_prime(3), i.e. once for each witness. - -=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 deleted file mode 100644 index e2fcabf370..0000000000 --- a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application -specific data to DSA structures - -=head1 SYNOPSIS - - #include - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod deleted file mode 100644 index e1e30b9a07..0000000000 --- a/src/lib/libcrypto/doc/DSA_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -DSA_new, DSA_free - allocate and free DSA objects - -=head1 SYNOPSIS - - #include - - DSA* DSA_new(void); - - void DSA_free(DSA *dsa); - -=head1 DESCRIPTION - -DSA_new() allocates and initializes a B structure. It is equivalent to -calling DSA_new_method(NULL). - -DSA_free() frees the B structure and its components. The values are -erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, DSA_new() returns B and sets an error -code that can be obtained by -L. Otherwise it returns a pointer -to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod deleted file mode 100644 index bc57a3e8e2..0000000000 --- a/src/lib/libcrypto/doc/DSA_set_method.pod +++ /dev/null @@ -1,143 +0,0 @@ -=pod - -=head1 NAME - -DSA_set_default_method, DSA_get_default_method, -DSA_set_method, DSA_new_method, DSA_OpenSSL, -DSA_set_default_openssl_method, DSA_get_default_openssl_method -- select DSA method - -=head1 SYNOPSIS - - #include - #include - - void DSA_set_default_method(const DSA_METHOD *meth); - - const DSA_METHOD *DSA_get_default_method(void); - - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - - DSA *DSA_new_method(ENGINE *engine); - - DSA_METHOD *DSA_OpenSSL(void); - -=head1 DESCRIPTION - -A B specifies the functions that OpenSSL uses for DSA -operations. By modifying the method, alternative implementations -such as hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these DSA API functions are affected by the use -of B API calls. - -Initially, the default DSA_METHOD is the OpenSSL internal implementation, -as returned by DSA_OpenSSL(). - -DSA_set_default_method() makes B the default method for all DSA -structures created later. B: This is true only whilst no ENGINE has -been set as a default for DSA, so this function is no longer recommended. - -DSA_get_default_method() returns a pointer to the current default -DSA_METHOD. However, the meaningfulness of this result is dependent on -whether the ENGINE API is being used, so this function is no longer -recommended. - -DSA_set_method() selects B to perform all operations using the key -B. This will replace the DSA_METHOD used by the DSA key and if the -previous method was supplied by an ENGINE, the handle to that ENGINE will -be released during the change. It is possible to have DSA keys that only -work with certain DSA_METHOD implementations (eg. from an ENGINE module -that supports embedded hardware-protected keys), and in such cases -attempting to change the DSA_METHOD for the key can have unexpected -results. - -DSA_new_method() allocates and initializes a DSA structure so that B -will be used for the DSA operations. If B is NULL, the default engine -for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD -controlled by DSA_set_default_method() is used. - -=head1 THE DSA_METHOD STRUCTURE - -struct - { - /* name of the implementation */ - const char *name; - - /* sign */ - DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, - DSA *dsa); - - /* pre-compute k^-1 and r */ - int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, - BIGNUM **rp); - - /* verify */ - int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some - implementations) */ - int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, - BIGNUM *a2, BIGNUM *p2, BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *in_mont); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, - const BIGNUM *p, const BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *m_ctx); - - /* called at DSA_new */ - int (*init)(DSA *DSA); - - /* called at DSA_free */ - int (*finish)(DSA *DSA); - - int flags; - - char *app_data; /* ?? */ - - } DSA_METHOD; - -=head1 RETURN VALUES - -DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective -Bs. - -DSA_set_method() returns non-zero if the provided B was successfully set -as the method for B (including unloading the ENGINE handle if the previous -method was supplied by an ENGINE). - -DSA_new_method() returns NULL and sets an error code that can be -obtained by L if the allocation -fails. Otherwise it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DSA_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B modules. If a -default ENGINE is specified for DSA functionality using an ENGINE API function, -that will override any DSA defaults set using the DSA API (ie. -DSA_set_default_method()). For this reason, the ENGINE API is the recommended -way to control default implementations for use in DSA and other cryptographic -algorithms. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), -DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. - -DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced -DSA_set_default_method() and DSA_get_default_method() respectively, and -DSA_set_method() and DSA_new_method() were altered to use Bs rather than -Bs during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DSA API without -requiring changing these function prototypes. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_sign.pod b/src/lib/libcrypto/doc/DSA_sign.pod deleted file mode 100644 index 4e78a71390..0000000000 --- a/src/lib/libcrypto/doc/DSA_sign.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures - -=head1 SYNOPSIS - - #include - - int DSA_sign(int type, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); - - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, - BIGNUM **rp); - - int DSA_verify(int type, const unsigned char *dgst, int len, - unsigned char *sigbuf, int siglen, DSA *dsa); - -=head1 DESCRIPTION - -DSA_sign() computes a digital signature on the B byte message -digest B using the private key B and places its ASN.1 DER -encoding at B. The length of the signature is places in -*B. B must point to DSA_size(B) bytes of memory. - -DSA_sign_setup() may be used to precompute part of the signing -operation in case signature generation is time-critical. It expects -B to contain DSA parameters. It places the precomputed values -in newly allocated Bs at *B and *B, after freeing -the old ones unless *B and *B are NULL. These values may -be passed to DSA_sign() in Bkinv> and Br>. -B is a pre-allocated B or NULL. - -DSA_verify() verifies that the signature B of size B -matches a given message digest B of size B. -B is the signer's public key. - -The B parameter is ignored. - -=head1 RETURN VALUES - -DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. -DSA_verify() returns 1 for a valid signature, 0 for an incorrect -signature and -1 on error. The error codes can be obtained by -L. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DSA_sign() and DSA_verify() are available in all versions of SSLeay. -DSA_sign_setup() was added in SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod deleted file mode 100644 index ba4f650361..0000000000 --- a/src/lib/libcrypto/doc/DSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DSA_size - get DSA signature size - -=head1 SYNOPSIS - - #include - - int DSA_size(const DSA *dsa); - -=head1 DESCRIPTION - -This function returns the size of an ASN.1 encoded DSA signature in -bytes. It can be used to determine how much memory must be allocated -for a DSA signature. - -Bq> must not be B. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod b/src/lib/libcrypto/doc/EC_GFp_simple_method.pod deleted file mode 100644 index aff20ac175..0000000000 --- a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B objects. - -=head1 SYNOPSIS - - #include - - const EC_METHOD *EC_GFp_simple_method(void); - const EC_METHOD *EC_GFp_mont_method(void); - const EC_METHOD *EC_GFp_nist_method(void); - const EC_METHOD *EC_GFp_nistp224_method(void); - const EC_METHOD *EC_GFp_nistp256_method(void); - const EC_METHOD *EC_GFp_nistp521_method(void); - - const EC_METHOD *EC_GF2m_simple_method(void); - - int EC_METHOD_get_field_type(const EC_METHOD *meth); - -=head1 DESCRIPTION - -The Elliptic Curve library provides a number of different implementations through a single common interface. -When constructing a curve using EC_GROUP_new (see L) an -implementation method must be provided. The functions described here all return a const pointer to an -B structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation -type for the form of curve selected is used. - -For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. - -For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All -other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the -use of montgomery multiplication (see L). EC_GFp_nist_method -offers an implementation optimised for use with NIST recommended curves (NIST curves are available through -EC_GROUP_new_by_curve_name as described in L). - -The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit -optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these -implementations are not available on all platforms. - -EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either -F2^m or Fp. If the field type is Fp then the value B is returned. If the field type is -F2^m then the value B is returned. These values are defined in the -obj_mac.h header file. - -=head1 RETURN VALUES - -All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. - -EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. - -=head1 SEE ALSO - -L, L, L, L, -L, L, L, -L, -L - -=cut diff --git a/src/lib/libcrypto/doc/EC_GROUP_copy.pod b/src/lib/libcrypto/doc/EC_GROUP_copy.pod deleted file mode 100644 index d4896af1d5..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_copy.pod +++ /dev/null @@ -1,174 +0,0 @@ -=pod - -=head1 NAME - -EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); - EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); - - const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); - - int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); - const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); - - int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - - void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); - int EC_GROUP_get_curve_name(const EC_GROUP *group); - - void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); - int EC_GROUP_get_asn1_flag(const EC_GROUP *group); - - void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); - point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); - - unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); - size_t EC_GROUP_get_seed_len(const EC_GROUP *); - size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); - - int EC_GROUP_get_degree(const EC_GROUP *group); - - int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); - - int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); - - int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); - - int EC_GROUP_get_basis_type(const EC_GROUP *); - int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); - -=head1 DESCRIPTION - -EC_GROUP_copy copies the curve B into B. Both B and B must use the same EC_METHOD. - -EC_GROUP_dup creates a new EC_GROUP object and copies the content from B to the newly created -EC_GROUP object. - -EC_GROUP_method_of obtains the EC_METHOD of B. - -EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These -paramaters include the B, the B and the B. The B is a well defined point on the -curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and -n-1 where n is the B. The B multipied by the B gives the number of points on the curve. - -EC_GROUP_get0_generator returns the generator for the identified B. - -The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B and B parameters -with the respective order and cofactors for the B. - -The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively -(see L). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name -will return 0. - -The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not. -If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions -EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then -the curve_name must also be set. - -The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). -point_conversion_form_t is an enum defined as follows: - - typedef enum { - /** the point is encoded as z||x, where the octet z specifies - * which solution of the quadratic equation y is */ - POINT_CONVERSION_COMPRESSED = 2, - /** the point is encoded as z||x||y, where z is the octet 0x02 */ - POINT_CONVERSION_UNCOMPRESSED = 4, - /** the point is encoded as z||x||y, where the octet z specifies - * which solution of the quadratic equation y is */ - POINT_CONVERSION_HYBRID = 6 - } point_conversion_form_t; - - -For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by -the octets for x, followed by the octets for y. - -For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For -POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of -the two possible solutions for y has been used, followed by the octets for x. - -For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two -possible solutions for y has been used, followed by the octets for x, followed by the octets for y. - -The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form -for the curve respectively. - -ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages -in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. -If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library -does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block -containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the -builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using -EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use -this seed value, although it will be preserved in any ASN1 based communications. - -EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be -the value m. - -The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid. -For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is -simply b. In either case for the curve to be valid the discriminant must be non zero. - -The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include -verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has -the correct order. - -EC_GROUP_cmp compares B and B to determine whether they represent the same curve or not. - -The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves -defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial -function f(x). This function is either a trinomial of the form: - -f(x) = x^m + x^k + 1 with m > k >= 1 - -or a pentanomial of the form: - -f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 - -The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The -function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B. Similarly -the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B, -B and B respectively. - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, -EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. - -EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. - -EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. - -EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. - -EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form -and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the -specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0. - -EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not -specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. - -EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is -0, the return value will be 1. On error 0 is returned. - -EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. - -EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in ) for a -trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. - -=head1 SEE ALSO - -L, L, L, -L, L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_GROUP_new.pod b/src/lib/libcrypto/doc/EC_GROUP_new.pod deleted file mode 100644 index 9ab3566e65..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_new.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - - EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_by_curve_name(int nid); - - int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - -=head1 DESCRIPTION - -Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the -prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised -elliptic curve equation as follows: - -y^2 mod p = x^3 +ax + b mod p - -The second form is those defined over a binary field F2^m where the elements of the field are integers of length at -most m bits. For this form the elliptic curve equation is modified to: - -y^2 + xy = x^3 + ax^2 + b (where b != 0) - -Operations in a binary field are performed relative to an B. All such curves with OpenSSL -use a trinomial or a pentanomial for this parameter. - -A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B (see -L). It is then necessary to call either EC_GROUP_set_curve_GFp or -EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. - -EC_GROUP_set_curve_GFp sets the curve parameters B

represents -the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three -or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. -EC_group_get_curve_GF2m obtains the previously set curve parameters. - -The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the -appropriate EC_group_set_curve function. An appropriate default implementation method will be used. - -Whilst the library can be used to create any curve using the functions described above, there are also a number of -predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function -EC_get_builtin_curves. The parameter B should be an array of EC_builtin_curve structures of size B. The function -will populate the B array with information about the builtin curves. If B is less than the total number of -curves available, then the first B curves will be returned. Otherwise the total number of curves will be -provided. The return value is the total number of curves available (whether that number has been populated in B or -not). Passing a NULL B, or setting B to 0 will do nothing other than return the total number of curves available. -The EC_builtin_curve structure is defined as follows: - - typedef struct { - int nid; - const char *comment; - } EC_builtin_curve; - -Each EC_builtin_curve item has a unique integer id (B), and a human readable comment string describing the curve. - -In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B of the curve to -be constructed. - -EC_GROUP_free frees the memory associated with the EC_GROUP. - -EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. - -=head1 RETURN VALUES - -All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. - -EC_get_builtin_curves returns the number of builtin curves that are available. - -EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. - -=head1 SEE ALSO - -L, L, L, -L, L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_KEY_new.pod b/src/lib/libcrypto/doc/EC_KEY_new.pod deleted file mode 100644 index 02d7bac82c..0000000000 --- a/src/lib/libcrypto/doc/EC_KEY_new.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_KEY *EC_KEY_new(void); - int EC_KEY_get_flags(const EC_KEY *key); - void EC_KEY_set_flags(EC_KEY *key, int flags); - void EC_KEY_clear_flags(EC_KEY *key, int flags); - EC_KEY *EC_KEY_new_by_curve_name(int nid); - void EC_KEY_free(EC_KEY *key); - EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); - EC_KEY *EC_KEY_dup(const EC_KEY *src); - int EC_KEY_up_ref(EC_KEY *key); - const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); - int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); - const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); - int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); - const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); - int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); - void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void *EC_KEY_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); - int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); - int EC_KEY_generate_key(EC_KEY *key); - int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); - -=head1 DESCRIPTION - -An EC_KEY represents a public key and (optionally) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new. -The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling -EC_KEY_set_group. - -Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L for a description of curve names. This function simply wraps calls to EC_KEY_new and -EC_GROUP_new_by_curve_name. - -Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated -with it. - -EC_KEY_copy copies the contents of the EC_KEY in B into B. - -EC_KEY_dup creates a new EC_KEY object and copies B into it. - -EC_KEY_up_ref increments the reference count associated with the EC_KEY object. - -EC_KEY_generate_key generates a new public and private key for the supplied B object. B must have an EC_GROUP object -associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order -of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the -private key. - -EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid. - -EC_KEY_set_public_key_affine_coordinates sets the public key for B based on its affine co-ordinates, i.e. it constructs an EC_POINT -object based on the supplied B and B values and sets the public key to be this EC_POINT. It will also performs certain sanity checks -on the key to confirm that it is valid. - -The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B respectively. - -The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the value of the encoding flags for the B. There are two encoding -flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the B is -converted into ASN1 in a call to i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded -along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key. - -The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B. For a description -of point_conversion_forms please refer to L. - -EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the -elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted. - -EC_KEY_set_flags sets the flags in the B parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B parameter. All other flags are left in their existing state. - -EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L for further information on the asn1_flag. - -EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L. - - -=head1 RETURN VALUES - -EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error. - -EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer. - -EC_KEY_copy returns a pointer to the destination key, or NULL on error. - -EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error. - -EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY. - -EC_KEY_get0_private_key returns the private key associated with the EC_KEY. - -EC_KEY_get_enc_flags returns the value of the current encoding flags for the EC_KEY. - -EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY. - - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_POINT_add.pod b/src/lib/libcrypto/doc/EC_POINT_add.pod deleted file mode 100644 index ae92640843..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_add.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B objects. - -=head1 SYNOPSIS - - #include - #include - - int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); - int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); - int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); - int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); - int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); - int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); - int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); - int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); - int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_have_precompute_mult(const EC_GROUP *group); - - -=head1 DESCRIPTION - -EC_POINT_add adds the two points B and B and places the result in B. Similarly EC_POINT_dbl doubles the point B and places the -result in B. In both cases it is valid for B to be one of B or B. - -EC_POINT_invert calculates the inverse of the supplied point B. The result is placed back in B. - -The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. - -EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. - -EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. - -The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine -co-ordinate system. In the case of EC_POINTs_make_affine the value B provides the number of points in the array B to be -forced. - -EC_POINT_mul calculates the value generator * B + B * B and stores the result in B. The value B may be NULL in which case the result is just B * B. - -EC_POINTs_mul calculates the value generator * B + B * B + ... + B * B. As for EC_POINT_mul the value -B may be NULL. - -The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst -EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L for information -about the generator. - - -=head1 RETURN VALUES - -The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, -EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. - -EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. - -EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. - -EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. - -EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libcrypto/doc/EC_POINT_new.pod b/src/lib/libcrypto/doc/EC_POINT_new.pod deleted file mode 100644 index b41ca0ed0c..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_new.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B objects. - -=head1 SYNOPSIS - - #include - #include - - EC_POINT *EC_POINT_new(const EC_GROUP *group); - void EC_POINT_free(EC_POINT *point); - void EC_POINT_clear_free(EC_POINT *point); - int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); - EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); - const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); - int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); - int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); - int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - -=head1 DESCRIPTION - -An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B -object that the point relates to. - -EC_POINT_free frees the memory associated with the EC_POINT. - -EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory. - -EC_POINT_copy copies the point B into B. Both B and B must use the same EC_METHOD. - -EC_POINT_dup creates a new EC_POINT object and copies the content from B to the newly created -EC_POINT object. - -EC_POINT_method_of obtains the EC_METHOD associated with B. - -A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity. - -The affine co-ordinates for a point describe a point in terms of its x and y position. The functions -EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B and B co-ordinates for the point -B

defined over the curve given in B. - -As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian -projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in -this co-ordinate system provides more efficient point multiplication operations. -A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is -mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and -EC_POINT_get_Jprojective_coordinates_GFp respectively. - -Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is -on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp -and EC_POINT_set_compressed_coordinates_GF2m functions where B is the x co-ordinate and B is a value 0 or 1 to identify which of -the two possible values for y should be used. - -In addition EC_POINTs can be converted to and from various external representations. Supported representations are octet strings, BIGNUMs and hexadecimal. The format of the external representation is described by the point_conversion_form. See L for -a description of point_conversion_form. Octet strings are stored in a buffer along with an associated buffer length. A point held in a BIGNUM is calculated by converting the point to an octet string and then converting that octet string into a BIGNUM integer. Points in hexadecimal format are stored in a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f). - -The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert -from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively. - -The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of -octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length. - -The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free -this memory with a subsequent call to free(). - -=head1 RETURN VALUES - -EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error. - -The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp, -EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, -EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, -EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point. - -EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. - -EC_POINT_point2oct returns the length of the required buffer, or 0 on error. - -EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error. - -EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error. - -EC_POINT_point2hex returns a pointer to the hex string, or NULL on error. - -EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error. - -=head1 SEE ALSO - -L, L, L, L, -L, L, -L, L - -=cut -- cgit v1.2.3-55-g6feb

, B and B for a curve over Fp stored in B. -EC_group_get_curve_GFp obtains the previously set curve parameters. - -EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B