ECC_MakeKeys

CryptoSys PKI Pro Manual

ECC_MakeKeys

Generates an EC public/private key pair and saves as two key files.

VBA/VB6 Syntax


Public Declare Function ECC_MakeKeys Lib "diCrPKI.dll" (ByVal strPubKeyFile As String, ByVal strPriKeyFile As String, ByVal strCurveName As String, ByVal strPassword As String, ByVal strParams As String, ByVal nOptions As Long) As Long

nRet = ECC_MakeKeys(strPublicKeyFile, strPrivateKeyFile, strCurveName, strPassword, strParams, nOptions)

C/C++ Syntax


long __stdcall ECC_MakeKeys(const char *szPubKeyFile, const char *szPriKeyFile, const char *szCurveName, const char *szPassword, const char *szParams, long nOptions);

Parameters

szPubKeyFile

[in] name of public key file to be created.

szPriKeyFile

[in] name of encrypted private key file to be created.

szCurveName

[in] name of elliptic curve (see remarks).

szPassword

[in] the password to be used for the encrypted key file.

szParams

[in] (optional) parameters. Set as the empty string "" for defaults. Otherwise include a set of attribute-value pairs separated by a semi-colon ";" to set options from the following

count=<nnn> to set the iteration count in the encrypted private key used in the PBKDF method, e.g. "count=5000;" [default=2048]
prf=<hmac-name> to change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacWithSHA256;" [default=hmacwithSHA1]
rngseed=<string> to add some extra user-specified additional seed for the random number generator, e.g. "rngseed=pqrrr1234xyz;"

Valid values for hmac-name are {hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}.

nOptions

[in] containing a flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from:
PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" (default)
PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC
PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC
PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC
PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC
(there are more options - see security options for encrypted private keys)
and optionally add
PKI_KEY_FORMAT_PEM to save the key files in PEM form (default is binary DER-encoded format).

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a nonzero error code.

VBA Wrapper Syntax

Public Function eccMakeKeys (szPubKeyFile As String, szPriKeyFile As String, szCurveName As String, szPassword As String, Optional szParams As String = "", Optional nOptions As Long = 0) As Long

.NET Equivalent

Ecc.MakeKeys Method

C++ (STL) Equivalent

static int dipki::Ecc::MakeKeys (const std::string &publicKeyFile, const std::string &privateKeyFile, Curve curve, const std::string &password, PbeScheme pbes=PbeScheme::Default, const std::string &paramString="", Format fileFormat=Format::Binary)

Python Equivalent

static Ecc.make_keys(pubkeyfile, prikeyfile, curvename, password, pbescheme=0, params='', fileformat=0)

Remarks

The public and private keys are encoded into ASN.1 values of type SubjectPublicKeyInfo and EncryptedPrivateKeyInfo respectively. Any existing files of the same names will be overwritten without warning. The password should be a string of non-zero ASCII characters.

The key is stored by default as a pair of DER-encoded binary files. Use the PKI_KEY_FORMAT_PEM flag to save in PEM-encoded format.

Supported curve names for szCurveName are:

Curve name	Alternative names	Remarks
`secp192r1`	`P-192`, `P_192`, `prime192v1`	NIST
`secp256r1`	`P-256`, `P_256`, `prime256v1`	NIST
`secp224r1`	`P-224`, `P_224`	NIST
`secp384r1`	`P-384`, `P_384`	NIST
`secp521r1`	`P-521`, `P_521`	NIST
`secp256k1`		Bitcoin/SEC
`Ed25519`		For EdDSA signatures
`X25519`		For ECDH key exchange
`Ed448`		For EdDSA signatures
`X448`		For ECDH key exchange
`brainpoolP256r1`		[RFC5639]
`brainpoolP384r1`		[RFC5639]
`brainpoolP512r1`		[RFC5639]

Valid values for the "prf" parameter in szParams are:

hmacWithSHA1 (default)
hmacWithSHA224
hmacWithSHA256
hmacWithSHA384
hmacWithSHA512

These are case-insensitive and work only with the PKI_PBE_PBKDF2_ options. This will override any PKI_HMAC_ flag in nOptions

Set szParams as the empty string "" for defaults.

Example

The following example creates two new key pairs for the NIST curves P-256 and P-521, respectively. The first example saves the private key using default options (pbeWithSHAAnd3-KeyTripleDES-CBC with an iteration count of 2048). The second example saves the private key using PBKDF2 with AES-256 as the encryption scheme, hmacWithSHA512 as the PRF algorithm, and an iteration count of 5000.

Dim nRet As Long
Dim strPublicKeyFile As String
Dim strPrivateKeyFile As String
Dim strPassword As String
Dim strCurve As String
Dim nChars As Long
Dim strTypeName As String
Dim strFileName As String

strPublicKeyFile = "myeckeyp256.pub"
strPrivateKeyFile = "myeckeyp256.p8"
strPassword = "password"
strCurve = "P-256"
' Create a new pair of ECC keys saved as DER-encoded files
nRet = ECC_MakeKeys(strPublicKeyFile, strPrivateKeyFile, strCurve, strPassword, "", 0)
Debug.Print "ECC_MakeKeys returns " & nRet & " (expected 0)"

strPublicKeyFile = "myeckeyp521.pub"
strPrivateKeyFile = "myeckeyp521.p8"
strPassword = "password"
strCurve = "P-521"
' Create a new pair of ECC keys saved as DER-encoded files
nRet = ECC_MakeKeys(strPublicKeyFile, strPrivateKeyFile, strCurve, strPassword, "count=5000;prf=hmacWithSHA512;", PKI_PBE_PBKDF2_AES256)
Debug.Print "ECC_MakeKeys returns " & nRet & " (expected 0)"

' Check the types of files we made
strTypeName = String(PKI_ASN1_TYPE_MAXCHARS, " ")
strFileName = strPublicKeyFile
nChars = ASN1_Type(strTypeName, Len(strTypeName), strFileName, 0)
If nChars > 0 Then Debug.Print strFileName & ": " & Left(strTypeName, nChars)
strFileName = strPrivateKeyFile
nChars = ASN1_Type(strTypeName, Len(strTypeName), strFileName, 0)
If nChars > 0 Then Debug.Print strFileName & ": " & Left(strTypeName, nChars)

ECC_MakeKeys returns 0 (expected 0)
ECC_MakeKeys returns 0 (expected 0)
myeckeyp521.pub: PUBLIC KEY INFO
myeckeyp521.p8: PKCS8 ENCRYPTED PRIVATE KEY

[Contents] [Index]

[PREV: ECC_KeyHashCode...] [Contents] [Index]

[NEXT: ECC_PublicKeyFromPrivate...]