Ecc class¶

class cryptosyspki.Ecc¶

Manage keys for elliptic curve cryptography.

class CurveName¶

Supported curve names.

BRAINPOOLP256R1 = 'brainpoolP256r1'¶: ECC Brainpool 256-bit curve

BRAINPOOLP384R1 = 'brainpoolP384r1'¶: ECC Brainpool 384-bit curve

BRAINPOOLP512R1 = 'brainpoolP512r1'¶: ECC Brainpool 512-bit curve

ED25519 = 'Ed25519'¶: safe curve for EdDSA

ED448 = 'Ed448'¶: safe curve for EdDSA

PRIME192V1 = 'prime192v1'¶: P-192

PRIME256V1 = 'prime256v1'¶: P-256

P_192 = 'P-192'¶: secp192r1

P_224 = 'P-224'¶: secp224r1

P_256 = 'P-256'¶: secp256r1

P_384 = 'P-384'¶: secp384r1

P_521 = 'P-521'¶: secp521r1

SECP192R1 = 'secp192r1'¶: P-192

SECP224R1 = 'secp224r1'¶: P-224

SECP256K1 = 'secp256k1'¶: "Bitcoin" curve

SECP256R1 = 'secp256r1'¶: P-256

SECP384R1 = 'secp384r1'¶: P-384

SECP521R1 = 'secp521r1'¶: P-521

X25519 = 'X25519'¶: Safe curve for ECDH

X448 = 'X448'¶: Safe curve for ECDH

class Format¶

Format for saved key file.

BINARY = 0¶: Binary (default)

DEFAULT = 0¶: Binary

PEM = 65536¶: PEM-encoded format

class KeyType¶

Key type for unencrypted key file.

Default is SubjectPublicKeyInfo for an EC public key or ECPrivateKey for an EC private key.

DEFAULT = 0¶: Save key in the default format.

LEGACY = 524288¶: Save a safe key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey)

PKCS8 = 262144¶: Save a NIST/SEC curve private key in PKCS#8 PrivateKeyInfo format (ignored for a public key).

PRIVATE_KEY = 0¶: Key value represents a private key (use for reading safe curves)

PUBLIC_KEY = 1¶: Key value represents a public key (use for reading safe curves)

class PbeScheme¶

Password-based encryption scheme to encrypt the private key file.

DEFAULT = 0¶: pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12

PBKDF2_AES128 = 4128¶: PBKDF2 using aes128-CBC

PBKDF2_AES192 = 4144¶: PBKDF2 using aes192-CBC

PBKDF2_AES256 = 4160¶: PBKDF2 using aes256-CBC

PBKDF2_DESEDE3 = 4112¶: PBKDF2 using des-EDE3-CBC

static dh_shared_secret(intprikeystr, intpubkeystr)¶

Compute EC Diffie-Hellman shared secret.

Parameters:

intprikeystr (str) -- Our own private key in internal string form.
intpubkeystr (str) -- Other party's public key in internal string form.

Returns:

Diffie-Hellman shared secret.

Return type:

bytes

static key_hashcode(intkeystr)¶

Compute the hash code of an "internal" ECC public or private key string.

Should be the same for a matching private and public key.

Parameters:: intkeystr (str) -- Internal key string.
Returns:: A 32-bit hash code for the key encoded in hex.
Return type:: str

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

Generate a new EC public/private key pair and save as two key files.

Parameters:

pubkeyfile (str) -- name of public key file to be created.
prikeyfile (str) -- name of encrypted private key file to be created.
curvename (Ecc.CurveName) -- name of elliptic curve.
password (str) -- password to be used for the encrypted key file.
pbescheme (Ecc.PbeScheme) -- Password-based encryption scheme to encrypt private key [default = pbeWithSHAAnd3-KeyTripleDES-CBC]
params (str) --
Optional parameters. A set of attribute "name=value" pairs separated by a semicolon (;) .
count=<integer>
To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048].

prf=<hmac-name>
To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;". Valid values are (case-insensitive):
hmacwithSHA1 (default)

hmacwithSHA224

hmacwithSHA256

hmacwithSHA384

hmacwithSHA512
rngseed=<string>
To add some user-supplied entropy for the key generation process, e.g. "rngseed=NaCl;".
fileformat (Ecc.Format) -- Format to save file [default = DER binary]

Returns:

Zero if successful.

Return type:

int

Example

>>> # Make default key pair using P-192 curve
>>> Ecc.make_keys("mykey.pub", "mykey.p8", Ecc.CurveName.P_192, "password")
0
>>> # Make key pair using P-384 with advanced options
>>> Ecc.make_keys("mypubkey384.pem", "myprikey384.pem", Ecc.CurveName.P_384, "password", Ecc.PbeScheme.PBKDF2_AES128, "count=3999;prf=hmacWithSha256", Ecc.Format.PEM)
0

static publickey_from_private(intkeystr)¶

Return an internal EC public key string from an internal EC private key string.

Parameters:: intkeystr (str) -- the private key as an internal key string
Returns:: The public key in ephemeral "internal" representation, or the empty string on error.
Return type:: str

Examples

>>> # Specify an EC private key in base58 form
>>> keyb58 = "6ACCbmy9qwiFcuVgvxNNwMPfoghobzznWrLs3v7t3RmN"
>>> curvename = "secp256k1"
>>> # Read in to an internal key
>>> intpristr = Ecc.read_key_by_curve(Cnv.tohex(Cnv.frombase58(keyb58)), curvename)
>>> # Extract public key from private key
>>> intpubstr = Ecc.publickey_from_private(intpristr)
>>> Ecc.query_key(intpristr, 'publicKey')
'04654bacc2fc7a3bde0f8eb95dc5aac9ba1df732255cf7f2eb7e1e8e6edbb1f4188ff3752ac4bdf1e3a31a488747745dddcbabd33a10c3b52d737c092851da13c0'
>>> # These should be the same
>>> Ecc.key_hashcode(intpubstr)
'BA36523B'
>>> Ecc.key_hashcode(intpristr)
'BA36523B'

static query_key(intkeystr, query)¶

Query an EC key string for selected information. May return an integer or a string.

Parameters:

intkeystr (str) -- containing the key as an internal key string
query (str) --
Query string (case-insensitive). Valid queries are:
- "curveName" -- Name of the curve.
- "keyBits" -- Number of bits in the key.
- "isPrivate" -- 1 if key is a private key; 0 if not.
- "privateKey" -- Value of the private key in hex format.
- "publicKey" -- Value of the public key in hex format.

Returns:

Result of query if found or an empty string if not found.

static read_key_by_curve(keyhex, curvename, ispublic=False)¶

Return an internal key string of an EC key from its hexadecimal representation.

Parameters:

keyhex (str) -- hexadecimal representation of the key, private or public
curvename (Ecc.CurveName) -- name of the elliptic curve
ispublic (bool) -- True if key is a public key, False if a private key. Required for safe curve keys, otherwise ignored.

Returns:

The key in ephemeral "internal" representation, or the empty string on error

For NIST/SEC curves, an EC private key w is represented as HEX(w) and a public key (x,y) in the uncompressed X9.63 form 04||HEX(x)||HEX(y). The key type is detected automatically and the ispublic argument is ignored.

For the safe curves, X25519 and Ed25519, both private and public keys are expected as the hexadecimal representation of a 32-byte value in little-endian format. The ispublic argument must be used to must specify whether the key is a private or public key.

Return type:

str

static read_private_key(keyfileorstr, password='')¶

Read from a file or string containing an EC private key into an "internal" private key string.

Parameters:

keyfileorstr (str) -- Name of file or a PEM string containing the key
password (str) -- Password for private key, if encrypted.

Returns:

Ephemeral internal representation of the private key

Return type:

str

Example

>>> intprikey = Ecc.read_private_key("mykey.p8", "password")
>>> Ecc.query_key(intprikey, 'curveName')
'secp192r1'

static read_public_key(keyfileorstr)¶

Read from a file or string containing an EC public key into an "internal" public key string.

Parameters:: keyfileorstr (str) -- Name of file or a PEM string containing the key
Returns:: Ephemeral internal representation of the public key.
Return type:: str

Example

>>> intpubkey = Ecc.read_public_key("mykey.pub")
>>> Ecc.query_key(intpubkey, 'isPrivate')
0

static save_enc_key(outputfile, intkeystr, password, pbescheme=0, params='', fileformat=0)¶

Save an internal EC private key string to an encrypted private key file.

Parameters:

outputfile (str) -- Name of key file to be created
intkeystr (str) -- the private EC key as an internal key string
password (str) -- Password for private key, if encrypted.
pbescheme (Ecc.PbeScheme) -- Encryption scheme to encrypt private key [default = pbeWithSHAAnd3-KeyTripleDES-CBC]
params (str) --
Optional parameters. A set of attribute name=value pairs separated by a semicolon ;.
count=<integer>:
To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048].

prf=<hmac-name>
To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;". Valid values are (case-insensitive):
hmacwithSHA1 (default)

hmacwithSHA224

hmacwithSHA256

hmacwithSHA384

hmacwithSHA512
fileformat (Ecc.Format) -- Format to save file [default = DER binary]

Returns:

Zero if successful.

Return type:

int

static save_key(outputfile, intkeystr, keytype=0, fileformat=0)¶

Save an internal EC key string (public or private) to an unencrypted key file.

Parameters:

outputfile (str) -- Name of key file to be created
intkeystr (str) -- the private or public EC key as an internal key string
keytype (Ecc.KeyType) -- Key structure for private key (ignored for public)
fileformat (Ecc.Format) -- Format to save file [default = DER binary]

Returns:

Zero if successful.

Return type:

int