# Difference between revisions of "Elliptic Curve Cryptography"

(Added description of F2m fields) |
m (→What is an Elliptic Curve?) |
||

(17 intermediate revisions by 4 users not shown) | |||

Line 1: | Line 1: | ||

The OpenSSL EC library provides support for Elliptic Curve Cryptography (ECC). It is the basis for the OpenSSL implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) and Elliptic Curve Diffie-Hellman (ECDH). | The OpenSSL EC library provides support for Elliptic Curve Cryptography (ECC). It is the basis for the OpenSSL implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) and Elliptic Curve Diffie-Hellman (ECDH). | ||

+ | |||

+ | Note: This page provides an overview of what ECC is. It also describes the low-level API for working with Elliptic Curves. If all you need is support for normal ECDSA and ECDH operations then you should normally use the high level EVP API. Refer to [[EVP]] for a description of the EVP API. Refer to [[EVP Signing and Verifying]] for how to perform digital signature operations (including using ECDSA), [[EVP Key Derivation]] for how to derive shared secrets using DH and ECDH, and [[EVP Key and Parameter Generation]] for details of how to create EC Keys. | ||

+ | |||

+ | == Why use Elliptic Curves? == | ||

+ | |||

+ | The primary advantage of using Elliptic Curve based cryptography is reduced key size and hence speed. Elliptic curve based algorithms use significantly smaller key sizes than their non elliptic curve equivalents. The difference in equivalent key sizes increases dramatically as the key sizes increase. The approximate equivalence in security strength for symmetric algorithms compared to standard asymmetric algorithms and elliptic curve algorithms is shown in the table below. | ||

+ | |||

+ | {| class="wikitable" | ||

+ | |- | ||

+ | ! Symmetric Key Length !! Standard asymmetric Key Length !! Elliptic Curve Key Length | ||

+ | |- | ||

+ | | 80 || 1024 || 160 | ||

+ | |- | ||

+ | | 112 || 2048 || 224 | ||

+ | |- | ||

+ | | 128 || 3072 || 256 | ||

+ | |- | ||

+ | | 192 || 7680 || 384 | ||

+ | |- | ||

+ | | 256 || 15360 || 512 | ||

+ | |} | ||

+ | |||

+ | As can be seen, to get equivalent strength to a 256 bit symmetric key, a standard asymmetric algorithm would have to use an enormous key of 15360 bits. Keys of this size are typically not practical due to the amount of processing power that would be required, and therefore the speed of the operations. However, with elliptic curve algorithms, the equivalent key length is 512 bits, which is entirely practical. | ||

== What is an Elliptic Curve? == | == What is an Elliptic Curve? == | ||

Line 11: | Line 34: | ||

* Multiplication distributes over addition. So if a, b and c are in the set then a * (b + c) = (a * b) + (a * c) | * Multiplication distributes over addition. So if a, b and c are in the set then a * (b + c) = (a * b) + (a * c) | ||

− | A finite field is simply a field where the set has a finite number of elements. So, for example, the set of all integers could not be used as the basis for a finite field because there are an infinite number of them. However the set of integers from | + | A finite field is simply a field where the set has a finite number of elements. So, for example, the set of all integers could not be used as the basis for a finite field because there are an infinite number of them. However the set of integers from 0 to 100 could form the basis of a finite field. |

So now we can define what an Elliptic Curve is. In general an Elliptic Curve is one of the form: | So now we can define what an Elliptic Curve is. In general an Elliptic Curve is one of the form: | ||

− | y² = x³ + ax + b, where x, y, a | + | y² = x³ + ax + b, where x, y, a and b are elements of some Field |

− | In Elliptic Curve Cryptography we further restrict this such that x, y, a | + | In Elliptic Curve Cryptography we further restrict this such that x, y, a and b are elements of a '''finite''' field. |

Contrary to its name Elliptic Curves do not form an ellipse! | Contrary to its name Elliptic Curves do not form an ellipse! | ||

Line 26: | Line 49: | ||

Point multiplication is the operation of taking a point on the curve and "multiplying" it by some number. In practice this is achieved through repeated addition and doubling operations. | Point multiplication is the operation of taking a point on the curve and "multiplying" it by some number. In practice this is achieved through repeated addition and doubling operations. | ||

− | So with our set of points on a curve (plus the special point, infinity) we can start doing | + | So with our set of points on a curve (plus the special point, infinity) we can start doing something useful. First of all we pick a point on the curve called the '''generator''' (we'll call it g). |

Now: | Now: | ||

Line 59: | Line 82: | ||

and so on. | and so on. | ||

− | The next common type of field is referred to as the binary field F<sub>2<sup>m</sup></sub>. Elements of a binary field are typically | + | The next common type of field is referred to as the binary field F<sub>2<sup>m</sup></sub>. Elements of a binary field are typically represented as polynomials and not as numbers. So for example an element could be: |

x<sup>4</sup>+x<sup>2</sup>+1 | x<sup>4</sup>+x<sup>2</sup>+1 | ||

Line 79: | Line 102: | ||

== Defining Curves == | == Defining Curves == | ||

− | The parameters necessary for performing cryptographic operations for ECDH and ECDSA are simply the parameters required to set up the curve. Namely: the type of field e.g. prime (F<sub>p</sub>) or binary (F<sub>2<sup>m</sup></sub>), the value p | + | The parameters necessary for performing cryptographic operations for ECDH and ECDSA are simply the parameters required to set up the curve. Namely: the type of field e.g. prime (F<sub>p</sub>) or binary (F<sub>2<sup>m</sup></sub>), the value p for a prime field, the irreducible polynomial for a binary field, the values a and b from the curve equation, the generator point (g), the order and the cofactor. |

− | Fortunately unless you are defining a new curve (not recommended unless you know what you are doing), or you are using an unusual curve that OpenSSL does not have support for, you can usually utilise one of the '''named''' curves that are built-in to OpenSSL. These are a set of well known and widely used curves. The complete collection of curve parameters can be set in one go simply by selecting the appropriate named curve. | + | Fortunately unless you are defining a new curve (not recommended unless you know what you are doing), or you are using an unusual curve that OpenSSL does not have support for, you can usually utilise one of the '''named''' curves that are built-in to OpenSSL. These are a set of well known and widely used curves. The complete collection of curve parameters can be set in one go simply by selecting the appropriate named curve using [[Manual:EC_GROUP_new(3)|EC_GROUP_new_by_curve_name]]. |

− | <pre> | + | <pre>#include <openssl/obj_mac.h> |

− | + | #include <openssl/ec.h> | |

− | + | ... | |

− | |||

− | + | EC_GROUP *curve; | |

− | + | if(NULL == (curve = EC_GROUP_new_by_curve_name(NID_secp224r1))) | |

− | + | handleErrors();</pre> | |

+ | |||

+ | If a custom curve needs to be created, then it can be done as follows. This example code creates the same curve as the code above, but creates it "manually". In this example a prime field is being used, and the prime number is provided in the variable p. If a binary field was being created instead then a bit string representing the irreducible polynomial would have been provided in the p variable. For further information on the low level EC functions being used refer to the [[Manual:Ec(3)|EC]] manual pages: | ||

+ | |||

+ | <pre>EC_GROUP *create_curve(void) | ||

+ | { | ||

+ | BN_CTX *ctx; | ||

+ | EC_GROUP *curve; | ||

+ | BIGNUM *a, *b, *p, *order, *x, *y; | ||

+ | EC_POINT *generator; | ||

+ | |||

+ | /* Binary data for the curve parameters */ | ||

+ | unsigned char a_bin[28] = | ||

+ | {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, | ||

+ | 0xFF,0xFF,0xFF,0xFF,0xFF,0xFE,0xFF,0xFF,0xFF,0xFF, | ||

+ | 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFE}; | ||

+ | unsigned char b_bin[28] = | ||

+ | {0xB4,0x05,0x0A,0x85,0x0C,0x04,0xB3,0xAB,0xF5,0x41, | ||

+ | 0x32,0x56,0x50,0x44,0xB0,0xB7,0xD7,0xBF,0xD8,0xBA, | ||

+ | 0x27,0x0B,0x39,0x43,0x23,0x55,0xFF,0xB4}; | ||

+ | unsigned char p_bin[28] = | ||

+ | {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, | ||

+ | 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x00,0x00,0x00,0x00, | ||

+ | 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01}; | ||

+ | unsigned char order_bin[28] = | ||

+ | {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, | ||

+ | 0xFF,0xFF,0xFF,0xFF,0x16,0xA2,0xE0,0xB8,0xF0,0x3E, | ||

+ | 0x13,0xDD,0x29,0x45,0x5C,0x5C,0x2A,0x3D }; | ||

+ | unsigned char x_bin[28] = | ||

+ | {0xB7,0x0E,0x0C,0xBD,0x6B,0xB4,0xBF,0x7F,0x32,0x13, | ||

+ | 0x90,0xB9,0x4A,0x03,0xC1,0xD3,0x56,0xC2,0x11,0x22, | ||

+ | 0x34,0x32,0x80,0xD6,0x11,0x5C,0x1D,0x21}; | ||

+ | unsigned char y_bin[28] = | ||

+ | {0xbd,0x37,0x63,0x88,0xb5,0xf7,0x23,0xfb,0x4c,0x22, | ||

+ | 0xdf,0xe6,0xcd,0x43,0x75,0xa0,0x5a,0x07,0x47,0x64, | ||

+ | 0x44,0xd5,0x81,0x99,0x85,0x00,0x7e,0x34}; | ||

+ | |||

+ | /* Set up the BN_CTX */ | ||

+ | if(NULL == (ctx = BN_CTX_new())) handleErrors(); | ||

+ | |||

+ | /* Set the values for the various parameters */ | ||

+ | if(NULL == (a = BN_bin2bn(a_bin, 28, NULL))) handleErrors(); | ||

+ | if(NULL == (b = BN_bin2bn(b_bin, 28, NULL))) handleErrors(); | ||

+ | if(NULL == (p = BN_bin2bn(p_bin, 28, NULL))) handleErrors(); | ||

+ | if(NULL == (order = BN_bin2bn(order_bin, 28, NULL))) handleErrors(); | ||

+ | if(NULL == (x = BN_bin2bn(x_bin, 28, NULL))) handleErrors(); | ||

+ | if(NULL == (y = BN_bin2bn(y_bin, 28, NULL))) handleErrors(); | ||

+ | |||

+ | /* Create the curve */ | ||

+ | if(NULL == (curve = EC_GROUP_new_curve_GFp(p, a, b, ctx))) handleErrors(); | ||

+ | |||

+ | /* Create the generator */ | ||

+ | if(NULL == (generator = EC_POINT_new(curve))) handleErrors(); | ||

+ | if(1 != EC_POINT_set_affine_coordinates_GFp(curve, generator, x, y, ctx)) | ||

+ | handleErrors(); | ||

+ | |||

+ | /* Set the generator and the order */ | ||

+ | if(1 != EC_GROUP_set_generator(curve, generator, order, NULL)) | ||

+ | handleErrors(); | ||

+ | |||

+ | EC_POINT_free(generator); | ||

+ | BN_free(y); | ||

+ | BN_free(x); | ||

+ | BN_free(order); | ||

+ | BN_free(p); | ||

+ | BN_free(b); | ||

+ | BN_free(a); | ||

+ | BN_CTX_free(ctx); | ||

+ | |||

+ | return curve; | ||

+ | }</pre> | ||

+ | |||

+ | ==Working with Keys== | ||

+ | |||

+ | Keys for ECDH and ECDSA are represented using an [[Manual:EC_KEY_new(3)|EC_KEY]] structure in the low level [[Manual:Ec(3)|EC]] API. If you are using the preferred high-level [[EVP]] API then this EC_KEY structure will be wrapped in an [[EVP#EVP Working with EVP_PKEYs|EVP_PKEY]] object. | ||

+ | |||

+ | Creating a new EC_KEY is a process of creating a curve as described above, creating a new EC_KEY object, and then setting the key to use the curve using the [[Manual:EC_KEY_new(3)|EC_KEY_set_group]] function. Alternatively, the creation of the curve and the key can be done in one step as shown below using [[Manual:EC_KEY_new(3)|EC_KEY_new_by_curve_name]]: | ||

+ | |||

+ | <pre>#include <openssl/obj_mac.h> | ||

+ | #include <openssl/ec.h> | ||

+ | ... | ||

+ | |||

+ | EC_KEY *key; | ||

+ | |||

+ | if(NULL == (key = EC_KEY_new_by_curve_name(NID_secp224r1))) | ||

+ | handleErrors();</pre> | ||

+ | |||

+ | At this point the EC_KEY object has been set up and associated with the curve - but it is empty. There is no key data in it. In order to generate new keys for use with the EVP interface see [[EVP Key and Parameter Generation]]. To generate them using the low level API this can be done as follows: | ||

+ | |||

+ | <pre> | ||

+ | if(1 != EC_KEY_generate_key(key)) handleErrors(); | ||

</pre> | </pre> | ||

− | If a | + | Note that this operation generates a public and private key '''pair'''. Alternatively you may already know either the private key, the public key, or both. Setting the private key and/or public key is done as follows: |

+ | |||

+ | <pre>BIGNUM *prv; | ||

+ | EC_POINT *pub; | ||

+ | |||

+ | /* Set up private key in prv */ | ||

+ | /* Set up public key in pub */ | ||

+ | |||

+ | if(1 != EC_KEY_set_private_key(key, prv)) handleErrors(); | ||

+ | if(1 != EC_KEY_set_public_key(key, pub)) handleErrors();</pre> | ||

+ | |||

+ | If you set the private key then you '''must''' also set the public key. There have been occasional questions on the openssl-users email list from people who only have the private key but do not know the public key. Fortunately calculating the public key is simply a matter of multiplying the private key by the generator for the curve using [[Manual:EC_POINT_add(3)|EC_POINT_mul]]: | ||

+ | |||

+ | <pre>if (1 != EC_POINT_mul(curve, pub, prv, NULL, NULL, ctx)) | ||

+ | handleErrors();</pre> | ||

+ | |||

+ | Finally, it is possible to convert a low-level EC_KEY object into an EVP_PKEY object using the EVP_PKEY_set1_EC_KEY function described in the manual here: [[Manual:EVP_PKEY_set1_RSA(3)]] | ||

+ | |||

+ | ==Named Curves== | ||

+ | |||

+ | If you want to save a key and later load it with <tt>SSL_CTX_use_PrivateKey_file</tt>, then you '''must''' set the <tt>OPENSSL_EC_NAMED_CURVE</tt> flag on the key. You do that by calling <tt>EC_KEY_set_asn1_flag(ecKey, OPENSSL_EC_NAMED_CURVE)</tt>. Failure to do so will result in a SSL error of 0x1408a0c1 (no shared cipher) at the server. | ||

+ | |||

+ | As an example, the following creates a elliptic curve key and saves it using a named curve rather than an expanded list of group paramters: | ||

+ | |||

+ | <pre>EC_KEY *key = NULL; | ||

+ | |||

+ | key = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); | ||

+ | EC_KEY_set_asn1_flag(key, OPENSSL_EC_NAMED_CURVE);</pre> | ||

+ | |||

+ | If you want to detect the flags after reading a key or certificate from disk, then use the following code: | ||

− | <pre> | + | <pre>int EC_KEY_get_asn1_flag(const EC_KEY* key) |

− | |||

{ | { | ||

− | + | if (key) | |

− | + | { | |

− | + | const EC_GROUP* group = EC_KEY_get0_group(key); | |

− | + | if (group) | |

+ | return EC_GROUP_get_asn1_flag(group); | ||

− | + | return 0; | |

− | + | } | |

− | + | } | |

− | + | ... | |

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | + | int flags = EC_KEY_get_asn1_flag(ecKey); | |

− | + | ASSERT(flags & OPENSSL_EC_NAMED_CURVE);</pre> | |

− | + | The certificates below were dumped with <tt>openssl x509 -in server-ecdsa-cert.pem -text -noout</tt>. The certificate on the left was created with a key using <tt>OPENSSL_EC_NAMED_CURVE</tt>, while the certificate on the right was not. Notice the certificate on the left includes '''ASN1 OID: prime256v1'''. The certificate on the left can be used with SSL server using ECDSA, but the certificate on the right cannot because it will result in 0x1408a0c1 at the server. | |

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | + | {| align="center" | |

− | + | | [[File:cert-with-flag.png|thumb|350px|Figure 1: Key with OPENSSL_EC_NAMED_CURVE]] | |

− | + | | [[File:cert-without-flag.png|thumb|350px|Figure 2: Key without OPENSSL_EC_NAMED_CURVE]] | |

− | + | |} | |

− | |||

− | |||

− | |||

− | + | If you use a key or certificate without without the <tt>OPENSSL_EC_NAMED_CURVE</tt> flag (i.e., one that looks like the image on the right), then the SSL connection will fail with the following symptoms: | |

− | |||

− | + | <pre>Client (s_client): | |

− | |||

− | |||

− | |||

− | + | 139925962778272:error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure:s3_pkt.c:1256:SSL alert number 40 | |

− | + | 139925962778272:error:1409E0E5:SSL routines:SSL3_WRITE_BYTES:ssl handshake failure:s3_pkt.c:596:</pre> | |

− | |||

− | + | <pre>Server (s_server): | |

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | |||

− | + | 140339533272744:error:1408A0C1:SSL routines:SSL3_GET_CLIENT_HELLO:no shared cipher:s3_srvr.c:1353:</pre> | |

− | + | ||

+ | Note that OpenSSL's <tt>X509_verify</tt>, <tt>X509_verify_cert</tt>, <tt>SSL_CTX_check_private_key</tt>, <tt>SSL_CTX_use_PrivateKey_file</tt>, and <tt>SSL_CTX_use_certificate_chain_file</tt> will not return a failure when using a key or certificate in the wrong format. | ||

+ | |||

+ | |||

+ | ==See also== | ||

+ | * [[Elliptic Curve Diffie Hellman]] | ||

+ | * [[Command Line Elliptic Curve Operations]] | ||

+ | * [[Manual:ec(3)]] | ||

− | + | [[Category:C level]] | |

+ | [[Category:Cryptographic Algorithm]] | ||

+ | [[Category:Examples]] |

## Latest revision as of 20:12, 11 April 2016

The OpenSSL EC library provides support for Elliptic Curve Cryptography (ECC). It is the basis for the OpenSSL implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) and Elliptic Curve Diffie-Hellman (ECDH).

Note: This page provides an overview of what ECC is. It also describes the low-level API for working with Elliptic Curves. If all you need is support for normal ECDSA and ECDH operations then you should normally use the high level EVP API. Refer to EVP for a description of the EVP API. Refer to EVP Signing and Verifying for how to perform digital signature operations (including using ECDSA), EVP Key Derivation for how to derive shared secrets using DH and ECDH, and EVP Key and Parameter Generation for details of how to create EC Keys.

## Contents

## Why use Elliptic Curves?[edit]

The primary advantage of using Elliptic Curve based cryptography is reduced key size and hence speed. Elliptic curve based algorithms use significantly smaller key sizes than their non elliptic curve equivalents. The difference in equivalent key sizes increases dramatically as the key sizes increase. The approximate equivalence in security strength for symmetric algorithms compared to standard asymmetric algorithms and elliptic curve algorithms is shown in the table below.

Symmetric Key Length | Standard asymmetric Key Length | Elliptic Curve Key Length |
---|---|---|

80 | 1024 | 160 |

112 | 2048 | 224 |

128 | 3072 | 256 |

192 | 7680 | 384 |

256 | 15360 | 512 |

As can be seen, to get equivalent strength to a 256 bit symmetric key, a standard asymmetric algorithm would have to use an enormous key of 15360 bits. Keys of this size are typically not practical due to the amount of processing power that would be required, and therefore the speed of the operations. However, with elliptic curve algorithms, the equivalent key length is 512 bits, which is entirely practical.

## What is an Elliptic Curve?[edit]

First of all some terminology. We need to define what is meant by a field. In essence a field is a **set** of elements with operations defined for the elements of that set that equate to something like addition, substraction, multiplication and division. The elements could be numbers, or they could be something else entirely. In order to be a field the following conditions also have to be met:

- Both addition and multiplicaiton are closed over the set, so for example if a and b are in the set then so are a + b and a * b
- Addition and multiplication must be associative: so a + (b + c) = (a + b) + c and similarly for multiplication
- Addition and multiplication must be commutative: so a + b = b + a and similarly for multiplication
- Both addition and multiplication must have identity elements. So, for example 0 and 1 where: a + 0 = a, and a * 1 = a
- There must be additive and multiplicative inverses for all elements in the set. So, for example, for every element a in the set there is also a -a so that a + (-a) = 0 (where 0 is the identity element for addition). Similarly for multiplication.
- Multiplication distributes over addition. So if a, b and c are in the set then a * (b + c) = (a * b) + (a * c)

A finite field is simply a field where the set has a finite number of elements. So, for example, the set of all integers could not be used as the basis for a finite field because there are an infinite number of them. However the set of integers from 0 to 100 could form the basis of a finite field.

So now we can define what an Elliptic Curve is. In general an Elliptic Curve is one of the form: y² = x³ + ax + b, where x, y, a and b are elements of some Field

In Elliptic Curve Cryptography we further restrict this such that x, y, a and b are elements of a **finite** field.

Contrary to its name Elliptic Curves do not form an ellipse!

Ok, so far so good - but now it gets a bit more complicated! As well as the points on our curve we add an additional "special" point known as infinity. Using this set of points (i.e. all the points on the curve and infinity), we can define some operations on this set, which we call Point Addition and Point Multiplication.

Points on a curve are given in terms of their x and y co-ordinates, (x, y). Point Addition is essentially an operation which takes any two given points on a curve and yields a third point which is also on the curve. The maths behind this gets a bit complicated but think of it in these terms. Plot two points on an elliptic curve. Now draw a straight line which goes through both points. That line will intersect the curve at some third point. That third point is the result of the addition operation. Point Doubling is similar and can be thought of as adding a point to itself. Imagine a point on the curve and draw a straight line which is a tangent to the curve at that point. The result of the Point Doubling operation is where that tangent line intersects the curve at some other point.

Point multiplication is the operation of taking a point on the curve and "multiplying" it by some number. In practice this is achieved through repeated addition and doubling operations.

So with our set of points on a curve (plus the special point, infinity) we can start doing something useful. First of all we pick a point on the curve called the **generator** (we'll call it g).

Now:

- 0g = infinity
- 1g = g
- 2g = g + g
- 3g = g + g + g (or 2g + g)
- and so on.

Remember g, 2g and 3g are all points on the curve, and **+** in this context means point addition as defined above. If you keep going in this way you will eventually come to some number (lets call it **n**), such that ng = infinity. The set of points generated by repeatedly adding g to itself, along with the Point Addition operation together form a mathematical structure known as a **group**.

If you are lucky then you may have chosen a curve and a g, such that continually adding g to itself will eventually visit all of the possible points on the curve - but often this is not the case. The number **n** as defined above, is called the **order** of g. For various complicated mathematical reasons it also turns out that the total number of points that exist on the curve is divisble by n. Dividing the total number of points by n gives you another number known as the cofactor.

The security of Elliptic Curve Cryptography comes from the fact that given some point on the curve kg, (where k is a number and g is the known generator point), it is difficult to work out what the value of **k** is. This is known as the **discrete logarithm problem**. In the Elliptic Curve Cryptography algorithms ECDH and ECDSA, the point kg would be a public key, and the number k would be the private key.

## Types of Field[edit]

In principle there are many different types of field that could be used for the values x and y of a point (x, y). In practice however there are two primary ones used, and these are the two that are supported by the OpenSSL EC library.

The simplest is typically referred to as the prime field F_{p} where p is a prime number. In cryptographic applications p must be a very large prime number. The elements of the set are simply the numbers 0 through to p-1, and addition and multiplication over the field have the normal meaning for modular (or clock) arithmetic. So, if p=7 then the elements of the set are {0, 1, 2, 3, 4, 5, 6} and:

0 + 1 = 1

2 + 3 = 5

3 + 3 = 6

4 + 3 = 0

5 + 4 = 2

and so on.

The next common type of field is referred to as the binary field F_{2m}. Elements of a binary field are typically represented as polynomials and not as numbers. So for example an element could be:

x^{4}+x^{2}+1

This can then be expressed as a binary number ({1 0 1 0 1} in this case), where each term represents one bit in the binary representation. Addition of such polynomials is done as normal but with the result of each term reduced modulo 2. So for example:

(x^{2} + 1) + (x^{2} + x) = 2x^{2} + x + 1

Each term is then reduced modulo 2 to give an answer 0x^{2} + x +1 = x + 1

In binary representation this sum could be expressed as follows:

{1 0 1} + {1 1 0} = {0 1 1}

Note then that addition is just a simple XOR operation.

Multiplication in the binary field is done respective to an **irreducible polynomial**. Multiplication of polynomials is done in the normal way and the result is then divided by the irreducible polynomial. The remainder is the result of the multiplication. See http://en.wikipedia.org/wiki/Finite_field_arithmetic, for a discussion of binary field arithmetic.

## Defining Curves[edit]

The parameters necessary for performing cryptographic operations for ECDH and ECDSA are simply the parameters required to set up the curve. Namely: the type of field e.g. prime (F_{p}) or binary (F_{2m}), the value p for a prime field, the irreducible polynomial for a binary field, the values a and b from the curve equation, the generator point (g), the order and the cofactor.

Fortunately unless you are defining a new curve (not recommended unless you know what you are doing), or you are using an unusual curve that OpenSSL does not have support for, you can usually utilise one of the **named** curves that are built-in to OpenSSL. These are a set of well known and widely used curves. The complete collection of curve parameters can be set in one go simply by selecting the appropriate named curve using EC_GROUP_new_by_curve_name.

#include <openssl/obj_mac.h> #include <openssl/ec.h> ... EC_GROUP *curve; if(NULL == (curve = EC_GROUP_new_by_curve_name(NID_secp224r1))) handleErrors();

If a custom curve needs to be created, then it can be done as follows. This example code creates the same curve as the code above, but creates it "manually". In this example a prime field is being used, and the prime number is provided in the variable p. If a binary field was being created instead then a bit string representing the irreducible polynomial would have been provided in the p variable. For further information on the low level EC functions being used refer to the EC manual pages:

EC_GROUP *create_curve(void) { BN_CTX *ctx; EC_GROUP *curve; BIGNUM *a, *b, *p, *order, *x, *y; EC_POINT *generator; /* Binary data for the curve parameters */ unsigned char a_bin[28] = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF,0xFE,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFE}; unsigned char b_bin[28] = {0xB4,0x05,0x0A,0x85,0x0C,0x04,0xB3,0xAB,0xF5,0x41, 0x32,0x56,0x50,0x44,0xB0,0xB7,0xD7,0xBF,0xD8,0xBA, 0x27,0x0B,0x39,0x43,0x23,0x55,0xFF,0xB4}; unsigned char p_bin[28] = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01}; unsigned char order_bin[28] = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0x16,0xA2,0xE0,0xB8,0xF0,0x3E, 0x13,0xDD,0x29,0x45,0x5C,0x5C,0x2A,0x3D }; unsigned char x_bin[28] = {0xB7,0x0E,0x0C,0xBD,0x6B,0xB4,0xBF,0x7F,0x32,0x13, 0x90,0xB9,0x4A,0x03,0xC1,0xD3,0x56,0xC2,0x11,0x22, 0x34,0x32,0x80,0xD6,0x11,0x5C,0x1D,0x21}; unsigned char y_bin[28] = {0xbd,0x37,0x63,0x88,0xb5,0xf7,0x23,0xfb,0x4c,0x22, 0xdf,0xe6,0xcd,0x43,0x75,0xa0,0x5a,0x07,0x47,0x64, 0x44,0xd5,0x81,0x99,0x85,0x00,0x7e,0x34}; /* Set up the BN_CTX */ if(NULL == (ctx = BN_CTX_new())) handleErrors(); /* Set the values for the various parameters */ if(NULL == (a = BN_bin2bn(a_bin, 28, NULL))) handleErrors(); if(NULL == (b = BN_bin2bn(b_bin, 28, NULL))) handleErrors(); if(NULL == (p = BN_bin2bn(p_bin, 28, NULL))) handleErrors(); if(NULL == (order = BN_bin2bn(order_bin, 28, NULL))) handleErrors(); if(NULL == (x = BN_bin2bn(x_bin, 28, NULL))) handleErrors(); if(NULL == (y = BN_bin2bn(y_bin, 28, NULL))) handleErrors(); /* Create the curve */ if(NULL == (curve = EC_GROUP_new_curve_GFp(p, a, b, ctx))) handleErrors(); /* Create the generator */ if(NULL == (generator = EC_POINT_new(curve))) handleErrors(); if(1 != EC_POINT_set_affine_coordinates_GFp(curve, generator, x, y, ctx)) handleErrors(); /* Set the generator and the order */ if(1 != EC_GROUP_set_generator(curve, generator, order, NULL)) handleErrors(); EC_POINT_free(generator); BN_free(y); BN_free(x); BN_free(order); BN_free(p); BN_free(b); BN_free(a); BN_CTX_free(ctx); return curve; }

## Working with Keys[edit]

Keys for ECDH and ECDSA are represented using an EC_KEY structure in the low level EC API. If you are using the preferred high-level EVP API then this EC_KEY structure will be wrapped in an EVP_PKEY object.

Creating a new EC_KEY is a process of creating a curve as described above, creating a new EC_KEY object, and then setting the key to use the curve using the EC_KEY_set_group function. Alternatively, the creation of the curve and the key can be done in one step as shown below using EC_KEY_new_by_curve_name:

#include <openssl/obj_mac.h> #include <openssl/ec.h> ... EC_KEY *key; if(NULL == (key = EC_KEY_new_by_curve_name(NID_secp224r1))) handleErrors();

At this point the EC_KEY object has been set up and associated with the curve - but it is empty. There is no key data in it. In order to generate new keys for use with the EVP interface see EVP Key and Parameter Generation. To generate them using the low level API this can be done as follows:

if(1 != EC_KEY_generate_key(key)) handleErrors();

Note that this operation generates a public and private key **pair**. Alternatively you may already know either the private key, the public key, or both. Setting the private key and/or public key is done as follows:

BIGNUM *prv; EC_POINT *pub; /* Set up private key in prv */ /* Set up public key in pub */ if(1 != EC_KEY_set_private_key(key, prv)) handleErrors(); if(1 != EC_KEY_set_public_key(key, pub)) handleErrors();

If you set the private key then you **must** also set the public key. There have been occasional questions on the openssl-users email list from people who only have the private key but do not know the public key. Fortunately calculating the public key is simply a matter of multiplying the private key by the generator for the curve using EC_POINT_mul:

if (1 != EC_POINT_mul(curve, pub, prv, NULL, NULL, ctx)) handleErrors();

Finally, it is possible to convert a low-level EC_KEY object into an EVP_PKEY object using the EVP_PKEY_set1_EC_KEY function described in the manual here: Manual:EVP_PKEY_set1_RSA(3)

## Named Curves[edit]

If you want to save a key and later load it with `SSL_CTX_use_PrivateKey_file`, then you **must** set the `OPENSSL_EC_NAMED_CURVE` flag on the key. You do that by calling `EC_KEY_set_asn1_flag(ecKey, OPENSSL_EC_NAMED_CURVE)`. Failure to do so will result in a SSL error of 0x1408a0c1 (no shared cipher) at the server.

As an example, the following creates a elliptic curve key and saves it using a named curve rather than an expanded list of group paramters:

EC_KEY *key = NULL; key = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); EC_KEY_set_asn1_flag(key, OPENSSL_EC_NAMED_CURVE);

If you want to detect the flags after reading a key or certificate from disk, then use the following code:

int EC_KEY_get_asn1_flag(const EC_KEY* key) { if (key) { const EC_GROUP* group = EC_KEY_get0_group(key); if (group) return EC_GROUP_get_asn1_flag(group); return 0; } } ... int flags = EC_KEY_get_asn1_flag(ecKey); ASSERT(flags & OPENSSL_EC_NAMED_CURVE);

The certificates below were dumped with `openssl x509 -in server-ecdsa-cert.pem -text -noout`. The certificate on the left was created with a key using `OPENSSL_EC_NAMED_CURVE`, while the certificate on the right was not. Notice the certificate on the left includes **ASN1 OID: prime256v1**. The certificate on the left can be used with SSL server using ECDSA, but the certificate on the right cannot because it will result in 0x1408a0c1 at the server.

If you use a key or certificate without without the `OPENSSL_EC_NAMED_CURVE` flag (i.e., one that looks like the image on the right), then the SSL connection will fail with the following symptoms:

Client (s_client): 139925962778272:error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure:s3_pkt.c:1256:SSL alert number 40 139925962778272:error:1409E0E5:SSL routines:SSL3_WRITE_BYTES:ssl handshake failure:s3_pkt.c:596:

Server (s_server): 140339533272744:error:1408A0C1:SSL routines:SSL3_GET_CLIENT_HELLO:no shared cipher:s3_srvr.c:1353:

Note that OpenSSL's `X509_verify`, `X509_verify_cert`, `SSL_CTX_check_private_key`, `SSL_CTX_use_PrivateKey_file`, and `SSL_CTX_use_certificate_chain_file` will not return a failure when using a key or certificate in the wrong format.