ECTester

Build status GitHub release license

Tests support and behavior of elliptic curve cryptography implementations on JavaCards (TYPE_EC_FP and TYPE_EC_F2M) and on selected software libraries. See our github for more info.

Support table Implementation guide Test runs Docs

JavaCard Elliptic curve algorithm support#

The JavaCard API has support for basic Elliptic Curve Cryptography, such as ECDH and ECDSA. However not many cards actually support these algorithms. The table below displays support and performance obtained by ECTester for common curve sizes. For detailed support and implementation tests see test runs.

Legend

*ECDH types
  1. ALG_EC_SVDP_DH
  2. ALG_EC_SVDP_DHC
  3. ALG_EC_SVDP_DH_PLAIN
  4. ALG_EC_SVDP_DHC_PLAIN
  5. ALG_EC_PACE_GM
  6. ALG_EC_SVDP_DH_PLAIN_XY
*ECDSA types
  1. ALG_ECDSA_SHA
  2. ALG_ECDSA_SHA_224
  3. ALG_ECDSA_SHA_256
  4. ALG_ECDSA_SHA_384
  5. ALG_ECDSA_SHA_512
*Colors

$ \mathbb{F}_p $ support

192b 256b 384b 521b
** ECDH ECDSA ECDH ECDSA ECDH ECDSA ECDH ECDSA
Athena IDProtect 1,2,3,4
148ms
a,b,c
265ms
1,2,3,4
206ms
a,b,c
365ms
1,2,3,4
448ms
a,b,c
737ms
1,2,3,4
937ms
a,b,c
1490ms
Feitian A22CR
GD SmartCafe 6.0 1,2,3,4
128ms
a,b,c,d,e
270ms
1,2,4,3
190ms
a,b,c,d,e
355ms
Infineon CJTOP 1,2,3,4
137ms(1) , 200ms
a,b,c,d,e
210ms(a) - 280ms(e)
1,2,3,4
166ms(1) , 266ms
a,b,c,d,e
263ms(a) - 329ms(e)
1,2,3,4
241ms(1) , 410ms
a,b,c,d,e
397ms(a) - 464ms(e)
NXP JCOP31 v2.4.1 1,2
122ms
a
257ms
1,2
189ms
a
392ms
NXP JCOP CJ2A081 1,2
75ms
a
151ms
1,2
123ms
a
241ms
NXP JCOP v2.4.2 R3 1,2
99ms
a,b,c
180ms
1,2
150ms
a,b,c
275ms

$ \mathbb{F}_p $ performance

Card Type 192b 256b 384b 521b
* * ECDH ECDSA ECDH ECDSA ECDH ECDSA ECDH ECDSA
Athena IDProtect
1a 147 110+163 209 148+228 448 279+473 937 537+970
2b 147 113+167 209 150+230 448 281+477 938 540+973
3c 148 114+165 209 150+231 448 281+475 937 540+972
4d 146 209 448 938
5e
6
Feitian A22CR
1a
2b
3c
4d
5e
6
GD SmartCafe 6.0
1a 128 110+135 192 145+197
2b 128 122+147 193 158+210
3c 126 123+147 190 158+209
4d 126 127+152 191 162+214
5e 127+152 162+214
6
Infineon CJTOP
1a 138 144+113 167 175+138 240 254+202
2b 208 151+120 267 183+144 414 262+207
3c 207 151+121 263 182+145 408 261+207
4d 205 176+145 264 207+169 408 286+232
5e 175+145 208+171 287+233
6
NXP JCOP31 v2.4.1
1a 122 140+167 190 192+260
2b 123 191
3c
4d
5e
6
NXP JCOP CJ2A081
1a 76 93+107 124 129+168
2b 76 124
3c
4d
5e
6
NXP JCOP v2.4.2 R3
1a 101 111+111 154 151+172
2b 96 114+113 154+178
3c 114+114 154+176
4d
5e
6

$ \mathbb{F}_{2^m} $

Support for binary field curves on cards is very weak, very little cards have any. For more information see JCAlgTest support table.

Implementation guide#

A basic example of EC KeyPair generation is visible below, for a more complete example see ECExample.java.
    
    // secp256r1 from http://www.secg.org/sec2-v2.pdf
    byte[] EC256_FP_P = new byte[]{
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x01,
            (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00,
            (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF,
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF};
    byte[] EC256_FP_A = new byte[]{
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x01,
            (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00,
            (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF,
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFC};
    byte[] EC256_FP_B = new byte[]{
            (byte) 0x5A, (byte) 0xC6, (byte) 0x35, (byte) 0xD8, (byte) 0xAA, (byte) 0x3A, (byte) 0x93, (byte) 0xE7,
            (byte) 0xB3, (byte) 0xEB, (byte) 0xBD, (byte) 0x55, (byte) 0x76, (byte) 0x98, (byte) 0x86, (byte) 0xBC,
            (byte) 0x65, (byte) 0x1D, (byte) 0x06, (byte) 0xB0, (byte) 0xCC, (byte) 0x53, (byte) 0xB0, (byte) 0xF6,
            (byte) 0x3B, (byte) 0xCE, (byte) 0x3C, (byte) 0x3E, (byte) 0x27, (byte) 0xD2, (byte) 0x60, (byte) 0x4B};
    byte[] EC256_FP_G = new byte[]{
            (byte) 0x04,
            (byte) 0x6B, (byte) 0x17, (byte) 0xD1, (byte) 0xF2, (byte) 0xE1, (byte) 0x2C, (byte) 0x42, (byte) 0x47,
            (byte) 0xF8, (byte) 0xBC, (byte) 0xE6, (byte) 0xE5, (byte) 0x63, (byte) 0xA4, (byte) 0x40, (byte) 0xF2,
            (byte) 0x77, (byte) 0x03, (byte) 0x7D, (byte) 0x81, (byte) 0x2D, (byte) 0xEB, (byte) 0x33, (byte) 0xA0,
            (byte) 0xF4, (byte) 0xA1, (byte) 0x39, (byte) 0x45, (byte) 0xD8, (byte) 0x98, (byte) 0xC2, (byte) 0x96,
            (byte) 0x4F, (byte) 0xE3, (byte) 0x42, (byte) 0xE2, (byte) 0xFE, (byte) 0x1A, (byte) 0x7F, (byte) 0x9B,
            (byte) 0x8E, (byte) 0xE7, (byte) 0xEB, (byte) 0x4A, (byte) 0x7C, (byte) 0x0F, (byte) 0x9E, (byte) 0x16,
            (byte) 0x2B, (byte) 0xCE, (byte) 0x33, (byte) 0x57, (byte) 0x6B, (byte) 0x31, (byte) 0x5E, (byte) 0xCE,
            (byte) 0xCB, (byte) 0xB6, (byte) 0x40, (byte) 0x68, (byte) 0x37, (byte) 0xBF, (byte) 0x51, (byte) 0xF5};
    byte[] EC256_FP_R = new byte[]{
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x00,
            (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF,
            (byte) 0xBC, (byte) 0xE6, (byte) 0xFA, (byte) 0xAD, (byte) 0xA7, (byte) 0x17, (byte) 0x9E, (byte) 0x84,
            (byte) 0xF3, (byte) 0xB9, (byte) 0xCA, (byte) 0xC2, (byte) 0xFC, (byte) 0x63, (byte) 0x25, (byte) 0x51};
    short EC256_FP_K = 1;

    // 1. Allocate the KeyPair object.
    // ! This should be done in the Applet constructor !
    KeyPair example = new KeyPair(KeyPair.ALG_EC_FP, (short) 256);

    // 2. If the key parts are not available, call genKeyPair.
    if (example.getPrivate() == null || example.getPublic() == null) {
        // Sometimes cards require this so we have the keyparts, to
        // set parameters on.
        try {
            example.genKeyPair();
        } catch (Exception ignored) {}
    }

    // 3. Get the key parts and set custom domain parameters on them.
    ECPrivateKey priv = (ECPrivateKey) example.getPrivate();
    ECPublicKey pub = (ECPublicKey) example.getPublic();

    priv.setFieldFP(EC256_FP_P, (short) 0, EC256_FP_P.length);
    pub.setFieldFP(EC256_FP_P, (short) 0, EC256_FP_P.length);

    priv.setA(EC256_FP_A, (short) 0, EC256_FP_A.length);
    pub.setA(EC256_FP_A, (short) 0, EC256_FP_A.length);

    priv.setB(EC256_FP_B, (short) 0, EC256_FP_B.length);
    pub.setB(EC256_FP_B, (short) 0, EC256_FP_B.length);

    priv.setG(EC256_FP_G, (short) 0, EC256_FP_G.length);
    pub.set(EC256_FP_G, (short) 0, EC256_FP_G.length);

    priv.setR(EC256_FP_R, (short) 0, EC256_FP_R.length);
    pub.setR(EC256_FP_R, (short) 0, EC256_FP_R.length);

    priv.setK(EC256_FP_K);
    pub.setK(EC256_FP_K);

    // 4. Generate the KeyPair over the custom set domain parameters.
    example.genKeyPair();
    // Now, the example keypair is ready for use.
    

Common JavaCard ECC usage pitfalls

The JavaCard ECC API is quite general in its requirements for implementations, which means different cards can behave differently and cause errors.

No curve is set by default

KeyPairs allocated with new KeyPair(type, size) might or might not have set some default domain parameters. Which means using keypair.genKeyPair() just after allocating a KeyPair object will probably result in an exception. Thus, it is always better to explicitly setup custom domain parameters, using a known/standard curve, before trying to generate the KeyPair.

genKeyPair() required to get key parts

On some cards a newly allocated KeyPair does not yet contain the individual key parts (the ECPublicKey and ECPrivateKey). Thus doing keypair.getPrivate() or keypair.getPublic() will return null. Which makes setting custom domain parameters on the key parts harder. This can usually be fixed by calling keypair.genKeyPair(), which however might throw an exception, and then setting the custom domain parameters on the now accessible key parts.

clearKey() behaviour

The keypair.clearKey() method might clear out the set domain parameters of the keypair as well as the key contents.

getK() behaviour

The ECKey.getK() method might throw an exception if the card does not support working with the cofactor value.

Test suite runs#

The results of various test suites, run on a set of cards are available below:
Card name Default Test vectors
Athena IDProtect results results
Feitian A22CR results results
GD Smartcafe 6.0 results results
Infineon CJTOP results results
JCardSim results results
NXP JCOP31 v2.4.1 results results
NXP JCOP CJ2A081 results results
NXP JCOP v2.4.2 R3 results results
NXP JCOP v2.4.2 R3 J2E145G results results

Docs#