ECDSA Keys and Signatures

EJBCA supports ECDSA signature keys in addition to RSA. You can create a CA using ECDSA keys both using the Admin GUI and the CLI (bin/ejbca.sh ca init).

This section provides information on ECDSA Keys and Signatures in the following sections:

Generated Keys and Certificates

When generating a CA in EJBCA, up to three keys and certificates are generated:

  • A CA signing keypair and certificate

  • An encryption keypair, used for encrypting keyrecovery information

  • An OCSP signer keypair and certificate

When using ECDSA keys, the CA signing keypair and the OCSP signer keypair will be the ECDSA keytype you select when creating the CA. The CA signing and OCSP signing certificate will be signed using your selected signature algorithm. The encryption keypair will always be RSA, using 1024 or 2048 bit key length. It uses the key length set in the Admin GUI or 2048 bit by default using the cli. A dummy encryption certificate will be created using SHA1WithRSA.

Using ECDSA with an HSM

See the section about HSM property parameters to see which keys can be of different sorts. Note that the keyEncryptKey can not be ECDSA, but should be an RSA key. Your HSM must support both ECDSA and RSA keys. You can use PKCS11HSMKeyTool from the clientToolBox to generate keys and certificate requests from an HSM.

PrimeKey has made a patches for the java issues with ECDSA. These patches are waiting for approval in the OpenJDK 7. You can get a compiled patch together with an installation script for Linux operating systems (can be adapted for Windows as well) from PrimeKey.

Sun Java PKCS#11 ECC key issue (fixed in recent JDKs)

If you are using an very old version of Java/JDK, and the clientToolBox tool in EJBCA to generate ECC keys in an HSM using the PKCS#11 interface you are likely to stumble on a bug in the JDK which prevents reading of the public key from the HSM. The clientToolBox tool needs to read the public key, generate a "dummy" certificate and assign that to the key label, so we have a public key certificate in the keystore retrieved from the Sun PKCS#11 provider.

This bug is present at least up to and including Oracle JDK 1.6u23. A fix has been merged though and is available in new releases of OpenJDK and Oracle JDK.

You can look at this issue in the EJBCA Jira for a solution to the problem: ECA-940

Using named Brainpool curves in Java PKCS#11

At the time of writing, Oracle Java does not have named curve definitions for the Brainpool curves. PrimeKey has made a patch which is waiting for approval in the OpenJDK 7. You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.

This issue is registered in the EJBCA Jira as ECA-2012.

The patch should work on all HSMs that have named curve support for Brainpool. It has been tested on SafeNet Luna SA and Utimaco CryptoServer. SafeNet ProtectServer supports Brainpool but not using named curves, see below for brainpool support on

ProtectServer using custom domain parameters.

With the patch applied you can create and use CAs with brainpool curves in the HSM. Example clientToolBox commands to generate a key:

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so brainpoolP160r1 keyAliasBp160 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /usr/lunasa/lib/libCryptoki2_64.so 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /etc/utimaco/libcs2_pkcs11.so brainpoolP160r1 keyAliasBp160 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /etc/utimaco/libcs2_pkcs11.so 1

Using SHA224WithECDSA in Java PKCS#11

At the time of writing, Oracle Java does not have support for SHA224WithECDSA in the PKCS#11 provider. PrimeKey has made a patch which is waiting for approval in the OpenJDK 7. You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.

This issue is registered in the EJBCA issue tracker as ECA-2013.

The patch should work on all HSMs that have support for SHA224WithECDSA. It has been tested on SafeNet Luna SA and Utimaco CryptoServer.

With the patch applied you can create CAs using HSMs with the SHA224WithECDSA algorithm.

Issue with explicit parameters in Java

In order to use elliptic curves with explicit parameters (as opposed to the standard named curves) you need to apply a patch to the file ECParameters.java. It is the same file as patched above for the bug.

  • Download the JDK source code and locate the file sun/security/ec/ECParameters.java.

  • Starting at line 210 there is code for handling of non named curve EC parameters. Remove the Exception thrown in line 208 and enable the code that is commented out.

  • Compile the class by running 'javac *.java' in the directory where the file is located.

  • Replace the existing sun/security/ec/ECParameters.class file in jre/lib/rt.jar with your patched and compiled version.

Using Brainpool ECC with SafeNet ProtectServer Gold HSM

Here we provide a guide for using Brainpool curves with the SafeNet ProtectServer Gold HSM. These steps were contributed by DGBK, Netherlands. ProtectServer needs explicit parameters for the Brainpool curves. Using explicit parameters have one disadvantage, at least when using the Sun PKCS#11 provider, and that is that you can not use the EJBCA tools to generate keys, but have to use the HSM vendors tools.

First you should apply the patch for explicit parameters, as described above. Then you are ready to start generating domain parameters and keys. These are the commands for ProtectServer Gold software version 3.33, firmware version 2.07.

  1. Create domain parameters file brainpoolP160r1.txt from ptk_c_administration_manual_rev-c.pdf, Appendix G, Sample EC Domain Parameter Files. Note that you must add "cofactor=01" last in the parameters file, the cofactor is always one (in the spec document) for brainpool curves (cofactor=1 does not work, it has to be 01).

  2. We have to configure the HSM to accept custom domain parameters (E flag):

    ./ctconf -fcE

  3. Import the domain parameters to the HSM:

    /ctkmu idp -s 1 -t ec -n brainpoolP160r1 brainpoolP160r1.txt

  4. Generate keys and a (dummy) certificate. The dummy certificate is needed for the java PKCS#11 provider, the DN does not matter.

    ./ctcert c -k -l bpkey -tec -s1 -CbrainpoolP160r1 -d30y

  5. Test the keys with:

    ./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 1

  6. Start EJBCA and create a new CA with CAToken Properties:

    sharedLibrary=/opt/PTK/lib/libcryptoki.so
    defaultKey=bpkey
    slotLabelType=SLOT_NUMBER
    slotLabelValue=1

ECC named curves vs explicit parameters

Normally you want to generate requests and certificates using named curves encoded in certificates and requests, this is what IETF recommends. In some cases you need to generate the request and certificate with explicit parameters instead, this is for instance mandated by ICAO for usage in CSCA's and DS's for ePassports.

  • When generating requests with clientToolBox PKCS11HSMKeyTool certreq you can specify a flag to use explicit parameters instead of named curves. Named curves is the default.

  • When creating CAs with ejbca.sh ca init you can specify a flag to use explicit parameters instead of named curves. Named curves is the default.

  • When EJBCA issues certificate with public keys from certificate requests (csr's) the key in the certificate will be the same as in the csr. If the csr uses explicit parameters, so will the issued certificate.

If you generate a CA with explicit ECC parameters in the CA certificate you will not be able to run commands like 'ejbca.sh ca listcas' because Java only supports named curves when serializing certificates. You can resolve this by adding the BC provider as the first provider:

$ sudo vi /etc/java-7-openjdk/security/java.security
security.provider.1=org.bouncycastle.jce.provider.BouncyCastleProvider
(renumber the ones below)

After editing this (make sure you edit the right file) you need to restart JBoss.

Named curves

EJBCA supports the curves that BouncyCastle supports, including named curves from Nist, SEC and X9.62. New curves may be supported without this list being updated, give it a try! See Bouncycastle wiki for more information about ECDSA curves.
X9.62 curves:

  • prime192v1

  • prime192v2

  • prime192v3

  • prime239v1

  • prime239v2

  • prime239v3

  • prime256v1

SEC curves:

  • sect571r1

  • sect409r1

  • sect283r1

  • sect233r1

  • sect163r2

  • secp521r1

  • secp256r1

  • secp224r1

  • secp384r1

Nist curves:

  • P-224

  • P-256

  • P-384

  • P-521

  • B-163

  • B-233

  • B-283

  • B-409

  • B-571

Teletrust curves:

  • brainpoolp160r1

  • brainpoolp160t1

  • brainpoolp192r1

  • brainpoolp192t1

  • brainpoolp224r1

  • brainpoolp224t1

  • brainpoolp256r1

  • brainpoolp256t1

  • brainpoolp320r1

  • brainpoolp320t1

  • brainpoolp384r1

  • brainpoolp384t1

  • brainpoolp512r1

  • brainpoolp512t1

ImplicitlyCA curves

X9.62 provides 3 alternatives for the parameters that can be found in an EC public key. One of these is named implicitlyCA and indicates that the parameters are defined else where, implicit in the name of the certification authority (CA) that issued the key. In this situation the actual parameters appear in the ASN.1 encoding of the key as a DER encoded NULL. As the definition says, when the key is used, the parameters will have to come from elsewhere. In EJBCA the parameters are configured in conf/cesecore.properties.

When creating a new CA using the implicitlyCA facility, you first configure your curve parameters in conf/cesecore.properties and issue commands:

  • ant clean

  • ant deploy

After restarting the application server you can now create a new CA using the name implicitlyCA instead of a curve name as keyspec in the Admin GUI or CLI. The CA certificate will now be created with the NULL encoding of the public key.

When issuing client certificates where the client public key uses implicitlyCA, you must allow key length 0 in the certificate profile, because EJBCA can not read the key length, since the parameters are defined elsewhere.

See Bouncycastle wiki for more information about the implicitlyCA facility.

The curve parameters in conf/cesecore.parameters are configured in Bouncycastle using the following code:

ECCurve curve = new ECCurve.Fp(
new BigInteger(ecdsa.implicitlyca.q), // q
new BigInteger(ecdsa.implicitlyca.a, 16), // a
new BigInteger(ecdsa.implicitlyca.b, 16)); // b
org.bouncycastle.jce.spec.ECParameterSpec implicitSpec = new org.bouncycastle.jce.spec.ECParameterSpec(
curve,
curve.decodePoint(Hex.decode(ecdsa.implicitlyca.g)), // G
new BigInteger(ecdsa.implicitlyca.n)); // n
ConfigurableProvider config = (ConfigurableProvider)Security.getProvider(BouncyCastleProvider.PROVIDER_NAME);
config.setParameter(ConfigurableProvider.EC_IMPLICITLY_CA, implicitSpec); 

Creating client certificates

You can also issue normal requests for client certificates using ECDSA keys.

All certificates signed by an ECDSA CA will naturally use ECDSA signatures, regardless if the client keys are RSA or ECDSA.

When batch generating client keys using the CLI command 'bin/ejbca.sh batch' you configure the type of client keys that will be generated in the file conf/batchtool.properties. The possible parameters are explained there. If using the implicitlyCA facility the same parameters as configured for the ca in conf/cesecore.properties are used.

Limitations

When using the implicitlyCA mode only one set of curve parameters can be set for the whole EJBCA instance. This means that if you have several CAs using ECDSA with implicitlyCA, they will all use the same curve parameters. You can mix implicitlyCA with named curves according to your liking.