Named Curves and User-Defined Parameters
The SafeNet Luna PCIe 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 Luna PCIe 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
#
#
# Curve name prime192v1
p = FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFF
a = FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFC
b = 64210519E59C80E70FA7E9AB72243049FEB8DEECC146B9B1
s = 3045AE6FC8422F64ED579528D38120EAE12196D5
x = 188DA80EB03090F67CBF20EB43A18800F4FF0AFD82FF1012
y = 07192B95FFC8DA78631011ED6B24CDD573F977A11E794811
q = FFFFFFFFFFFFFFFFFFFFFFFF99DEF836146BC9B1B4D22831
h = 1
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
# # # Curve name C2tnB191v1
m = 191
k1 = 9
k2 = 0
k3 = 0
a = 2866537B676752636A68F56554E12640276B649EF7526267
b = 2E45EF571F00786F67B0081B9495A3D95462F5DE0AA185EC
x = 36B3DAF8A23206F9C4F299D7B21A9C369137F2C84AE1AA0D
y = 765BE73433B3F95E332932E70EA245CA2418EA0EF98018FB
q = 40000000000000000000000004A20E90C39067C893BBB9A5
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
#
#
# Curve name brainpoolP160r1
p = E95E4A5F737059DC60DFC7AD95B3D8139515620F
a = 340E7BE2A280EB74E2BE61BADA745D97E8F7C300
b = 1E589A8595423412134FAA2DBDEC95C8D8675E58
x = BED5AF16EA3F6A4F62938C4631EB5AF7BDBCDBC3
y = 1667CB477A1A8EC338F94741669C976316DA6321
q = E95E4A5F737059DC60DF5991D45029409E60FC09
h = 1
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
#
#
# Curve name brainpoolP512r1
p=AADD9DB8DBE9C48B3FD4E6AE33C9FC07CB308DB3B3C9D20ED6639CCA703308717D4D9B009BC66842AECDA12AE6A380E62881FF2F2D82C68528AA6056583A48F3
a=7830A3318B603B89E2327145AC234CC594CBDD8D3DF91610A83441CAEA9863BC2DED5D5AA8253AA10A2EF1C98B9AC8B57F1117A72BF2C7B9E7C1AC4D77FC94CA
b=3DF91610A83441CAEA9863BC2DED5D5AA8253AA10A2EF1C98B9AC8B57F1117A72BF2C7B9E7C1AC4D77FC94CADC083E67984050B75EBAE5DD2809BD638016F723
x=81AEE4BDD82ED9645A21322E9C4C6A9385ED9F70B5D916C1B43B62EEF4D0098EFF3B1F78E2D0D48D50D1687B93B97D5F7C6D5047406A5E688B352209BCB9F822
y=7DDE385D566332ECC0EABFA9CF7822FDF209F70024A57B1AA000C55B881F8111B2DCDE494A5F485E5BCA4BD88A2763AED1CA2B2FA8F0540678CD1E0F3AD80892
q=AADD9DB8DBE9C48B3FD4E6AE33C9FC07CB308DB3B3C9D20ED6639CCA70330870553E5C414CA92619418661197FAC10471DB1D381085DDADDB58796829CA90069
h = 1
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
#
# Curve name prime192vx
p = FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFF
a = FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFC
b = 64210519E59C80E70FA7E9AB72243049FEB8DEECC146B9B13
s = 34545567685743523457
x = 188DA80EB03090F67CBF20EB43A18800F4FF0AFD82FF1012
y = 07192B95FFC8DA78631011ED6B24CDD573F977A11E794811
q = FFFFFFFFFFFFFFFFFFFFFFFF99DEF836146BC9B1B4D22831
h = 12323435765786
