From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod | 120 +++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod (limited to 'openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod') diff --git a/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod b/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod new file mode 100644 index 0000000..2f658dc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, +EC_GROUP_new, EC_GROUP_new_from_ecparameters, +EC_GROUP_new_from_ecpkparameters, +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 EC_GROUP +objects + +=head1 SYNOPSIS + + #include + + EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); + EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) + EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) + 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); + + ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params) + ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params) + + 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_new_from_ecparameters() will create a group from the +specified B and +EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B. + +EC_GROUP_set_curve_GFp sets the curve parameters B

, 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

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. +If B is NULL nothing is done. + +EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. +If B is NULL nothing is done. + +=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 + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3