Elliptic curve cryptography (ECC) functions

The ECC functions make use of the ECC support of the Crypto Express4S feature or later in CCA coprocessor mode. They require a minimum CCA firmware level of 4.2 on the coprocessor.

These functions are declared in: include/ica_api.h.

You can use the icainfo utility with option -c to list all elliptic curves that are supported by libica on your current system configuration. The availability of curves is, for example, dependent from whether cryptographic coprocessors in CCA mode are available, whether OpenSSL is in FIPS mode, or whether the whole system is in FIPS mode. For further information, see icainfo - Show available libica functions.

Create an elliptic curve (EC) key

An EC key pair consists of a scalar (D) and a point (X,Y), which lies on the related elliptic curve. Hereby, D is the private part and (X,Y) is the public part of the key.

The value of the private key D is specified by an octet string whose length depends on the domain parameters of the related elliptic curve. The public key (X,Y) can be derived from D and the curve’s domain parameters.

So an EC key pair is specified either by

• the curve and the D-value, or
• the curve-ID (NID value), D-value, and (X,Y).

In libica, an EC key pair is always specified by (NID, D, (X,Y)). The corresponding data type in libica is ICA_EC_KEY.

An ICA_EC_KEY object is called a public EC key, if (X,Y) is specified, but D is not specified. An ICA_EC_KEY object is called a private EC key if D is specified, and optionally also (X,Y).

A public EC key may be given in compressed form, which means that only the X-value is provided. The missing Y-value can be recalculated from the curve-ID (NID value), D, and X. However, libica does not support compressed public EC keys.

Calculate the Diffie-Hellman (DH) shared secret

In SSL/TLS, ECC is used together with the Diffie-Hellman key agreement protocol that allows two parties (A and B), each having an elliptic curve public/private key pair, to establish a shared secret (z) over an insecure channel. This shared secret may be directly used as a key, or to derive another key. The length of z is equal to the length of D. Unlike to plain RSA-based SSL/TLS key exchange, the DH shared secret (z-value) is not part of the SSL/TLS connection and therefore provides forward secrecy.

Create or verify an ECDSA signature

The Elliptic Curve Digital Signature Algorithm (ECDSA) is a variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. Given data is signed with an ECC private key and signature verification is done with an ECC public key. Signing given data using ECDSA results in different signatures when repeating the process, because the algorithm involves a random value (k). This random value is created internally by the signature creation process and is re-calculated when verifying the ECDSA signature.

An ECDSA signature is a tuple of two numbers (r,s). In libica, an ECDSA signature has always an even length, and r is given by the first half, and s by the second half of the signature. In some cases, for example, using the secp521 curve, r or s may have 65 or 66 bytes. In libica, additional 0x00 bytes are padded at the front in such cases to enforce that r and s have the same length as D.

Using ECC in FIPS mode

For FIPS 140-3 compliance, only a subset of elliptic curves is available: p256, p384, p521. All other curves, including Brainpool curves, Edwards curves (ED25519 and ED448) and Montgomery curves (X25519 and X448) are blocked. The three FIPS compliant curves are only available via CPACF and therefore require MSA9 (IBM z15® or later). On older machines, ECC via CPACF is not available. You can display the list of available curves on your system using the icainfo utility. The following screen shot is an example from an IBM z15 system running in FIPS mode:

# icainfo -c
-------------------------------------------------------
                 |         hardware        |
        EC curve |   dynamic  |   static   |  software
                 |            |  (msa=09)  |  
-----------------+------------+------------+-----------
      prime256v1 |     no     |    yes     |      -
       secp384r1 |     no     |    yes     |      -
       secp521r1 |     no     |    yes     |      -
-------------------------------------------------------
Built-in FIPS support: FIPS 140-3 mode active.

In column hardware - static, which indicates CPACF support, the current MSA-level is displayed.