Package Cryptodome :: Package PublicKey :: Module ECC

Module ECC

Elliptic Curve Cryptography (ECC) algorithms.

ECC is a modern and efficient type of public key cryptography. Its security is based on the difficulty to solve discrete logarithms on the field defined by specific equations involving points on a curve.

ECC can be used to perform signing/verification and asymmetric encryption/decryption.

The main benefit of ECC is that the size of a key is significantly smaller than with other, more traditional algorithms like RSA or DSA.

For instance, consider the security level equivalent to AES128: an RSA key of similar strength must have a modulus of 3072 bits (therefore the total size is 768 bytes, comprising modulus and private exponent). An ECC private needs as little as 256 bits (32 bytes).

This module provides mechanisms for generating new ECC keys, exporting them using widely supported formats like PEM or DER and importing them back.

This module currently supports only ECC keys defined over the standard NIST P-256 curve (see FIPS 186-4, Section D.1.2.3). More curves will be added in the future.

The following example demonstrates how to generate a new key, export it, and subsequentely reload it back into the application:

>>> from Cryptodome.PublicKey import ECC
>>>
>>> key = ECC.generate(curve='P-256')
>>> f = open('myprivatekey.pem','wt')
>>> f.write(key.export_key('PEM'))
>>> f.close()
...
>>> f = open('myprivatekey.pem','rt')
>>> key = RSA.import_key(f.read())

The ECC key can be used to perform or verify ECDSA signatures, see Cryptodome.Signature.DSS.

Classes
  EccPoint
A class to abstract a point over an Elliptic Curve.
  EccKey
A private or public key over an Elliptic Curve.
Functions
 
generate(**kwargs)
Generate a new private key on the given curve.
 
construct(**kwargs)
Build a new ECC key (private or public) starting from some base components.
 
import_key(encoded, passphrase=None)
Import an ECC key (public or private).
Function Details

generate(**kwargs)

 
Generate a new private key on the given curve.
Parameters:
  • curve (string) - Mandatory. It must be "P-256", "prime256v1" or "secp256r1".
  • randfunc (callable) - Optional. The RNG to read randomness from. If None, the system source is used.

construct(**kwargs)

 
Build a new ECC key (private or public) starting from some base components.
Parameters:
  • curve (string) - Mandatory. It must be "P-256", "prime256v1" or "secp256r1".
  • d (integer) - Only for a private key. It must be in the range [1..order-1].
  • point_x (integer) - Mandatory for a public key. X coordinate (affine) of the ECC point.
  • point_y (integer) - Mandatory for a public key. Y coordinate (affine) of the ECC point.

import_key(encoded, passphrase=None)

 

Import an ECC key (public or private).

Parameters:
  • encoded (bytes or a (multi-line) string) - The ECC key to import.

    An ECC public key can be:

    • An X.509 certificate, binary (DER) or ASCII (PEM)
    • An X.509 subjectPublicKeyInfo, binary (DER) or ASCII (PEM)
    • An OpenSSH line (e.g. the content of ~/.ssh/id_ecdsa, ASCII)

    An ECC private key can be:

    • In binary format (DER, see section 3 of RFC5915 or PKCS#8)
    • In ASCII format (PEM or OpenSSH)

    Private keys can be in the clear or password-protected.

    For details about the PEM encoding, see RFC1421/RFC1423.

  • passphrase (byte string) - The passphrase to use for decrypting a private key. Encryption may be applied protected at the PEM level or at the PKCS#8 level. This parameter is ignored if the key in input is not encrypted.
Returns:
An ECC key object (EccKey)
Raises:
  • ValueError - When the given key cannot be parsed (possibly because the pass phrase is wrong).