ecies

Introduction

This package is an implementation of the Elliptic Curve Integrated Encryption Scheme (ECIES), following the specification recommended in Victor Shoup's paper. We refer to this implementation as the "Shoup's version" of ECIES.

We noticed that while Botan and Bouncy Castle have implemented the Shoup's version of ECIES, we could not find a Golang package that implemented it. As a result, interactions of ECIES-encrypted data among ecosystems coded in different languages can be difficult. To address this, the Disney+Hotstar Security Team implemented the Shoup's version of ECIES in Golang and is contributing it back to the community.

According to the wiki, our implementation is compatible with the Botan and Bouncy Castle implementations.

The encryption flow is as follows:

1. The sender generates an ephemeral key pair (ephemeral public key and ephemeral private key)
2. The sender calculates a shared secret using the Key Agreement, getting ephemeral private key and receiver's public key as the input parameters
3. The sender derives keys using the Key Derivation Function, getting the shared secret as the input parameters
4. The sender retrieves two keys from the derived keys, one is for encryption and the other is for mac
5. The sender calculates cipher message using the Symmetric Cipher, getting the plain message and encryption key as the input parameters.
6. The sender calculates mac, getting the cipher message and mac key as the input parameters
7. The sender sends the ephemeral public key, the cipher message, and the mac to the receiver.

The decryption flow is as follows:

1. The receiver retrieves the ephemeral public key
2. The receiver calculates a shared secret using the Key Agreement, getting ephemeral public key and its own private key as the input parameters
3. The receiver derives keys using the Key Derivation Function, getting the shared secret as the input parameters
4. The receiver retrieves two keys from the derived keys, one is for encryption and the other is for mac
5. The receiver validates the mac, getting the cipher message and mac key as the input parameters
6. The receiver calculates the plain message using the Symmetric Cipher, getting the cipher message and encryption key as the input parameters.

Quick Start

import (
	"fmt"
)

func example1() {
	k, err := GenerateKey()
	if err != nil {
		panic("failed to generate key pair")
	}
	privateKey := k
	publicKey := k.PublicKey

	serializedPrivateKey := HexEncode(SerializePrivateKey(privateKey))
	serializedPublicKey := HexEncode(SerializePublicKey(publicKey))
	fmt.Println("privateKey=" + serializedPrivateKey)
	fmt.Println("publicKey=" + serializedPublicKey)

	deserializedPrivateKey := DeserializePrivateKey(HexDecodeWithoutError(serializedPrivateKey))
	deserializedPublicKey, err := DeserializePublicKey(HexDecodeWithoutError(serializedPublicKey))
	if err != nil {
		panic("failed to deserialize key pair")
	}
	fmt.Println(deserializedPrivateKey.D.Cmp(privateKey.D) == 0)
	fmt.Println(deserializedPublicKey.X.Cmp(publicKey.X) == 0)
	fmt.Println(deserializedPublicKey.Y.Cmp(publicKey.Y) == 0)

	ecies := NewECIES()
	plainText := "hello world"
	encryptedTextBytes, err := ecies.Encrypt(publicKey, []byte(plainText))
	if err != nil {
		panic("failed to encrypt message")
	}
	decryptedTextBytes, err := ecies.Decrypt(privateKey, encryptedTextBytes)
	if err != nil {
		panic("failed to decrypt message")
	}
	fmt.Println(string(decryptedTextBytes))

}

Usage

There are four key parts in the ECIES. They are Key Agreement, Key Derivation Function, Symmetric Cipher, and MAC. In our implementation, we provide interface for each of them so that developers can have their own implementations. We can use this method ecies.NewCustomizedECIES to use our own component. We can also switch to different curve by set the variable CURVE

Also, we provide a default implementation using this method ecies.NewECIES , the following is the details.

Benchmark

In this part, we are giving some benchmarks for different elliptic curves, they are P256、P384 and P521. Refer to here to get more details about these curves.

Test Machine configuration:

• CPU: Apple M1 Pro
• Memory: 16 GB
• OS: macOS Ventura 13.0.1

Benchmark Results

• P256 is also known as secp256r1, the benchmark of which is as below.

• P384 is also known as secp384r1, the benchmark of which is as below.

• P521 is also known as secp521r1, the benchmark of which is as below.

• For comparing with P256, we gave the benchmark of RSA3072 (RSA3072 has the same security level as P256).

Compatibility

So far, we have verified the compatibility with C++ Botan and Java BouncyCastle. Let's take the BouncyCastle as an example.

• BouncyCastle

<dependency>
   <groupId>org.bouncycastle</groupId>
   <artifactId>bcpkix-jdk18on</artifactId>
   <version>1.71</version>
</dependency>

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.SecureRandom;
import java.security.Security;
import java.security.spec.ECGenParameterSpec;
import javax.crypto.Cipher;
import org.bouncycastle.crypto.agreement.ECDHBasicAgreement;
import org.bouncycastle.crypto.digests.SHA256Digest;
import org.bouncycastle.crypto.engines.AESEngine;
import org.bouncycastle.crypto.engines.IESEngine;
import org.bouncycastle.crypto.generators.KDF2BytesGenerator;
import org.bouncycastle.crypto.macs.HMac;
import org.bouncycastle.crypto.modes.CBCBlockCipher;
import org.bouncycastle.crypto.paddings.PKCS7Padding;
import org.bouncycastle.crypto.paddings.PaddedBufferedBlockCipher;
import org.bouncycastle.crypto.util.DigestFactory;
import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPrivateKey;
import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPublicKey;
import org.bouncycastle.jcajce.provider.asymmetric.ec.IESCipher;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.jce.spec.IESParameterSpec;
import org.bouncycastle.util.BigIntegers;
import org.bouncycastle.util.encoders.Hex;

public class BouncyCastleECIES {

    static {
        Security.addProvider(new BouncyCastleProvider());
    }

    private static final String EC_ALGORITHM_NAME = "EC";
    private static final String CURVE = "secp256r1";

    private static final IESParameterSpec IES_PARAMETER_SPEC_FOR_AES_CBC =
        new IESParameterSpec(null, null, 128, 128, null);

    public static byte[] encrypt(byte[] plainText, BCECPublicKey publicKey) throws Exception {
        IESCipher cipher = getIESCipher();
        cipher.engineInit(Cipher.ENCRYPT_MODE, publicKey, IES_PARAMETER_SPEC_FOR_AES_CBC, new SecureRandom());
        return cipher.engineDoFinal(plainText, 0, plainText.length);
    }

    public static byte[] decrypt(byte[] cipherText, BCECPrivateKey privateKey) throws Exception {
        IESCipher cipher = getIESCipher();
        cipher.engineInit(Cipher.DECRYPT_MODE, privateKey, IES_PARAMETER_SPEC_FOR_AES_CBC, new SecureRandom());
        return cipher.engineDoFinal(cipherText, 0, cipherText.length);
    }


    public static KeyPair generateKeyPair() throws Exception {
        KeyPairGenerator keyGenerator =
            KeyPairGenerator.getInstance(EC_ALGORITHM_NAME, BouncyCastleProvider.PROVIDER_NAME);
        keyGenerator.initialize(new ECGenParameterSpec(CURVE));
        KeyPair keyPair = keyGenerator.generateKeyPair();
        return keyPair;
    }

    public static String serializePrivateKey(BCECPrivateKey privateKey) {
        byte[] bytes = BigIntegers.asUnsignedByteArray(privateKey.getD());
        return Hex.toHexString(bytes);
    }

    public static String serializePublicKey(BCECPublicKey publicKey) throws Exception {
        byte[] bytes = publicKey.getQ().getEncoded(false);
        return Hex.toHexString(bytes);
    }

    private static IESCipher getIESCipher() {
        IESCipher cipher = new IESCipher(
            new IESEngine(
                new ECDHBasicAgreement(),
                new KDF2BytesGenerator(new SHA256Digest()),
                new HMac(DigestFactory.createSHA256()),
                new PaddedBufferedBlockCipher(new CBCBlockCipher(new AESEngine()), new PKCS7Padding())), 0);
        return cipher;
    }

    // we can test the compatibility using the output data
    public static void main(String[] args) throws Exception {
        String msg="hello_ECIES";
        KeyPair keyPair = generateKeyPair();
        BCECPublicKey publicKey = (BCECPublicKey) keyPair.getPublic();
        BCECPrivateKey privateKey = (BCECPrivateKey) keyPair.getPrivate();
        System.out.println("privateKeyString: "+serializePrivateKey(privateKey));
        System.out.println("publicKeyString: "+serializePublicKey(publicKey));
        byte[] encData = encrypt(msg.getBytes(), publicKey);
        System.out.println("encMessage: "+Hex.toHexString(encData));
        byte[] plainData = decrypt(encData, privateKey);
        System.out.println(new String(plainData));
    }
}

By the code above, we output the privateKeyString and the encMessage. We can decrypt using the Go implementation below.

package main

import (
	"fmt"
	"github.com/hotstar/ecies"
)

func main() {
	privateKeyString := "" 
	encMessage := ""

	privateKey := ecies.DeserializePrivateKey(ecies.HexDecodeWithoutError(privateKeyString))
	cipher := ecies.NewECIES()
	palinMessage, _ := cipher.Decrypt(privateKey, ecies.HexDecodeWithoutError(encMessage))
	fmt.Println(string(palinMessage))
}