Elliptic Curve Cryptography (ECC)

You can use the elliptic curve cryptography functions in this toolkit to sign data using the ECDSA and EdDSA algorithms (see SIG_SignData and SIG_SignFile and the Sig class methods). [New in v20.0] You can also perform elliptic curve Diffie-Hellman key exchange (ECDH) - see ECC_DHSharedSecret.

You can create your own elliptic curve keys, and read, analyze and save keys in the standard key file formats, both encrypted and unencrypted. You can read a key file into an internal key string which is stored in encrypted form valid only for the current session. We support the following curves over prime fields:

• P-192, also known as secp192r1 and prime192v1
• P-256, also known as secp256r1 and prime256v1
• P-224, also known as secp224r1
• P-384, also known as secp384r1
• P-521, also known as secp521r1
• secp256k1 (the Bitcoin curve)
• Ed25519 (EdDSA only) [New in v20.0]
• X25519 (ECDH only) [New in v20.0]
• Ed448 (EdDSA only) [New in v22.0]
• X448 (ECDH only) [New in v22.0]
• brainpoolP256r1 [New in v20.4]
• brainpoolP384r1 [New in v20.4]
• brainpoolP512r1 [New in v20.4]

Creating a new ECC key pair

To create a new elliptic curve key pair, use the ECC_MakeKeys function. This creates two new files, an encrypted private key file and a public key file. You can use the ReadKey and SaveKey functions to read in and save these in different formats.

Key file format

In this toolkit, EC public key files are always stored as DER-encoded SubjectPublicKeyInfo types [RFC5480]. In a PEM-encoded file, this should begin with -----BEGIN PUBLIC KEY.

The three supported types (all DER-encoded) for an EC private key file are:

1. PKCS#8 EncryptedPrivateKeyInfo [RFC5208] encrypted with a password. This is the (only) output when using ECC_MakeKeys and ECC_SaveEncKey. In a PEM-encoded file, this should begin with -----BEGIN ENCRYPTED PRIVATE KEY.
2. ECPrivateKey [RFC5915]. This is the default output for a private key using ECC_SaveKey. In a PEM-encoded file, this should begin with -----BEGIN EC PRIVATE KEY.
3. Unencrypted PKCS#8 PrivateKeyInfo [RFC5208] (more recently renamed as OneAsymmetricKey [RFC5958] but identical in structure in this case). This is an optional output for a private key using ECC_SaveKey with the PKI_KEY_TYPE_PKCS8 option. In a PEM-encoded file, this should begin with -----BEGIN PRIVATE KEY.

Key files can be saved as binary (default) or PEM-encoded (with the PKI_KEY_FORMAT_PEM option). These encodings are detected automatically when reading a key file.

Use the ECC_ReadKeyByCurve function to read in a key in a hex format string, then you can save it as a file in a supported key format. If your key is in base58 encoding, use CNV_Base58ToBytes to decode, then CNV_HexStrFromBytes to obtain the hex form string (in .NET just use Cnv.ToHex(Cnv.FromBase58(b58str))).

To change the format of an EC key file, read the file into an "internal" string using ECC_ReadPrivateKey or ECC_ReadPublicKey, then save it as a file again using ECC_SaveKey or ECC_SaveEncKey. To obtain the public key from a private key, read the private key into an internal string and then use ECC_PublicKeyFromPrivate. To analyze an EC key file, read it into an internal string and use ECC_QueryKey.