Named Curves and User-Defined Parameters

Home >	SDK Reference Guide > Using the SDK > Named Curves and User-Defined Parameters

Named Curves and User-Defined Parameters

The SafeNet HSM is a PKCS#11 oriented device. Prior to firmware 4.6.7, the HSM firmware statically defined the NIST named curve OIDs and curve parameters. To expand on that capability and add flexibility, firmware 4.6.7 (SafeNet Network HSM 4.3) and later added support for Brainpool curve OIDs and curve parameters. Additional support was added to decode the ecParameters structure and use that data in the generation of keys as well as in signing and verification.

Curve Validation Limitations

The HSM can validate the curve parameters, however domain parameter validation guarantees only the consistency/sanity of the parameters and the most basic, well-known security properties. The HSM has no way of judging the quality of a user-specified curve.

It is therefore important that you perform Known Answer Tests to verify the operation of the HSM for any new Domain Parameter.set. To maintain NIST-FIPS compatibility the feature is selectively enabled with the feature being disabled by default. Therefore the Administrator must ‘opt-in’ by actively choosing to enable the appropriate HSM policy. Among other effects, this causes the HSM to display a shell/console message to the effect that the HSM is not operating in FIPS mode.

Storing Domain Parameters

Under PKCS#11 v2.20, Domain Parameters are stored in object attribute CKA_EC_PARAMS. The value of this parameter is the DER encoding of an ANSI X9.62 Parameters value.

Parameters ::= CHOICE {
ecParameters ECParameters,
namedCurve CURVES.&id({CurveNames}),
implicitlyCA NULL
}

Because PKCS#11 states that the implicitlyCA is not supported by cryptoki, therefore the CKA_EC_PARAMS attribute must contain the encoding of an ecParameters or a namedCurve. Cryptoki holds ECC key pairs in separate Private and Public key objects. Each object has its own CKA_EC_PARAMS attribute which must be provided when the object is created and cannot be subsequently changed.

Cryptoki also supports CKO_DOMAIN_PARAMETERS objects. These store Domain Parameters but perform no cryptographic operations. A Domain Parameters object is really only for storage. To generate a key pair, you must extract the attributes from the Domain Parameters object and insert them in the CKA_EC_PARAMS attribute of the Public key template. Cryptoki can create new ECC Public and Private key objects and Domain Parameters objects in the following ways:

•Objects can be directly stored using the C_CreateObject command

•Public and private key objects can be generated internally with the C_GenerateKeyPair command and the CKM_EC_KEY_PAIR_GEN mechanism.

•Objects can be imported in encrypted form using C_UnwrapKey command.

Using Domain Parameters

ECC keys may be used for Signature Generation and Verification with the CKM_ECDSA and CKM_ECDSA_SHA1 mechanism and Encryption and Decryption with the CKM_ECIES mechanism. These three mechanism are enhanced so that they fetch the Domain Parameters from the CKA_EC_PARAMS attribute for both ecParameters and namedCurve choice and not just namedCurve choice.

User Friendly Encoder

Using ECC with Cryptoki to create or generate ECC keys requires that the CKA_EC_PARAMS attribute be specified. This is a DER encoded binary array. Usually in public documents describing ECC curves the Domain Parameters are specified as a series of printable strings so the programmer faces the problem of converting these to the correct format for Cryptoki use.

The cryptoki library is extended to support functions called CA_EncodeECPrimeParams and CA_EncodeECChar2Params which allow an application to specify the parameter details of a new curve. These functions implement DER encoders to build the CKA_EC_PARAMS attribute from large integer presentations of the Domain Parameter values.

Refer to Sample Domain Parameter Files for some sample Domain Parameter files.

Application Interfaces

CA_EncodeECPrimeParams

#include “cryptoki.h”

CK_RV CA_ EncodeECPrimeParams (

CK_BYTE_PTR DerECParams, CK_ULONG_PTR DerECParams Len

CK_BYTE_PTR prime, CK_USHORT primelen,

CK_BYTE_PTR a, CK_USHORT alen,

CK_BYTE_PTR b, CK_USHORT blen,

CK_BYTE_PTR seed, CK_USHORT seedlen,

CK_BYTE_PTR x, CK_USHORT xlen,

CK_BYTE_PTR y, CK_USHORT ylen,

CK_BYTE_PTR order, CK_USHORT orderlen,

CK_BYTE_PTR cofactor, CK_USHORT cofactorlen,

);

Do DER enc of ECC Domain Parameters Prime

Parameters

DerECParams	Resultant Encoding (length prediction supported if NULL).
DerECParamsLen	Buffer len/Length of resultant encoding
prime	Prime modulus
primelen	Prime modulus len
a	Elliptic Curve coefficient a
alen	Elliptic Curve coefficient a length
b	Elliptic Curve coefficient b
blen	Elliptic Curve coefficient b length
seed	Seed (optional may be NULL)
seedlen	Seed length
x	Elliptic Curve point X coord
xlen	Elliptic Curve point X coord length
y	Elliptic Curve point Y coord
ylen	Elliptic Curve point Y coord length
order	Order n of the Base Point
orderlen	Order n of the Base Point length
cofactor	The integer h = #E(Fq)/n (optional)
cofactorlen	h length
Return	Status of operation. CKR_OK if ok.

CA_EncodeECChar2Params

#include “cryptoki.h”

CK_RV CA_EncodeECChar2Params(

CK_BYTE_PTR DerECParams, CK_ULONG_PTR DerECParams Len

CK_USHORT m,

CK_USHORT k1,

CK_USHORT k2,

CK_USHORT k3,

CK_BYTE_PTR a, CK_USHORT alen,

CK_BYTE_PTR b, CK_USHORT blen,

CK_BYTE_PTR seed, CK_USHORT seedlen,

CK_BYTE_PTR x, CK_USHORT xlen,

CK_BYTE_PTR y, CK_USHORT ylen,

CK_BYTE_PTR order, CK_USHORT orderlen,

CK_BYTE_PTR cofactor, CK_USHORT cofactorlen,

);

Do DER enc of ECC Domain Parameters 2^M

Parameters

DerECParams	Resultant Encoding (length prediction supported if NULL).
DerECParamsLen	Buffer len/Length of resultant encoding
M	Degree of field
k1	parameter in trinomial or pentanomial basis polynomial
k2	parameter in pentanomial basis polynomial
k3	parameter in pentanomial basis polynomial
a	Elliptic Curve coefficient a
alen	Elliptic Curve coefficient a length
b	Elliptic Curve coefficient b
blen	Elliptic Curve coefficient b length
seed	Seed (optional may be NULL)
seedlen	Seed length
x	Elliptic Curve point X coord
xlen	Elliptic Curve point X coord length
y	Elliptic Curve point Y coord
ylen	Elliptic Curve point Y coord length
order	Order n of the Base Point
orderlen	Order n of the Base Point length
cofactor	The integer h = #E(Fq)/n (optional)
cofactorlen	h length
Return	Status of operation. CKR_OK if ok.

Sample Domain Parameter Files

The following examples show some sample domain parameter files.

prime192v1

#
#This file describes the domain parameters of an EC curve
#
#File contains lines of text. All lines not of the form key=value are ignored.
#All values must be Hexidecimal numbers except m, k, k1, k2 and k3 which are decimal.
#Lines starting with '#' are comments.
#
#Keys recognised for fieldID values are -
#p          - only if the Curve is based on a prime field
#m          - only if the curve is based on a 2^M field
#k1, k2, k3 - these three only if 2^M field

#You should have these combinations of fieldID values -
#p          - if Curve is based on a prime field
#m,k1,k2,k3 - if curve is based on 2^M

#These are the values common to prime fields and polynomial fields.
#a          - field element A
#b          - field element B
#s          - this one is optional
#x          - field element Xg of the point G
#y          - field element Yg of the point G
#q          - order n of the point G
#h          - (optional) cofactor h

C2tnB191v1

#This file describes the domain parameters of an EC curve

#File contains lines of text. All lines not of the form key=value are ignored.

#All values must be Hexidecimal numbers except m, k, k1, k2 and k3 which are decimal.

#Lines starting with '#' are comments.

#Keys recognised for fieldID values are -

#p          - only if the Curve is based on a prime field

#m          - only if the curve is based on a 2^M field

#k1, k2, k3 - these three only if 2^M field

#You should have these combinations of fieldID values -

#p          - if Curve is based on a prime field

#m,k1,k2,k3 - if curve is based on 2^M

#
#

These are the values common to prime fields and polynomial fields.

#a          - field element A

#b          - field element B

#s          - this one is optional

#x          - field element Xg of the point G

#y          - field element Yg of the point G

#q          - order n of the point G

#h          - (optional) cofactor h

#
#

brainpoolP160r1

#
#This file describes the domain parameters of an EC curve

#File contains lines of text. All lines not of the form key=value are ignored.

#All values must be Hexidecimal numbers except m, k, k1, k2 and k3 which are decimal.

#Lines starting with '#' are comments.

#Keys recognised for fieldID values are -

#p          - only if the Curve is based on a prime field

#m          - only if the curve is based on a 2^M field

#k1, k2, k3 - these three only if 2^M field

#You should have these combinations of fieldID values -

#p          - if Curve is based on a prime field

#m,k1,k2,k3 - if curve is based on 2^M

#These are the values common to prime fields and polynomial fields.

#a          - field element A

#b          - field element B

#s          - this one is optional

#x          - field element Xg of the point G

#y          - field element Yg of the point G

#q          - order n of the point G

#h          - (optional) cofactor h

brainpoolP512r1

#This file describes the domain parameters of an EC curve

#File contains lines of text. All lines not of the form key=value are ignored.

#All values must be Hexidecimal numbers except m, k, k1, k2 and k3 which are decimal.

#Lines starting with '#' are comments.

#Keys recognised for fieldID values are -

#p          - only if the Curve is based on a prime field

#m          - only if the curve is based on a 2^M field

#k1, k2, k3 - these three only if 2^M field

#You should have these combinations of fieldID values -

#p          - if Curve is based on a prime field

#m,k1,k2,k3 - if curve is based on 2^M

#These are the values common to prime fields and polynomial fields.

#a          - field element A

#b          - field element B

#s          - this one is optional

#x          - field element Xg of the point G

#y          - field element Yg of the point G

#q          - order n of the point G

#h          - (optional) cofactor h

Bad Parameter File

#This file describes the domain parameters of an EC curve

#File contains lines of text. All lines not of the form key=value are ignored.

#All values must be Hexidecimal numbers except m, k, k1, k2 and k3 which are decimal.
#Lines starting with '#' are comments.

#Keys recognised for fieldID values are -

#p          - only if the Curve is based on a prime field

#m          - only if the curve is based on a 2^M field

#k1, k2, k3 - these three only if 2^M field

#You should have these combinations of fieldID values -

#p          - if Curve is based on a prime field

#m,k1,k2,k3 - if curve is based on 2^M

#These are the values common to prime fields and polynomial fields.

#a          - field element A

#b          - field element B

#s          - this one is optional

#x          - field element Xg of the point G

#y          - field element Yg of the point G

#q          - order n of the point G

#h          - (optional) cofactor h