ECC¶
ECC (Elliptic Curve Cryptography) 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 computed over a curve.
ECC can be used to create digital signatures or to perform a key exchange.
Compared to traditional algorithms like RSA, an ECC key is significantly smaller at the same security level. For instance, a 3072-bit RSA key takes 768 bytes whereas the equally strong NIST P-256 private key only takes 32 bytes (that is, 256 bits).
This module provides mechanisms for generating new ECC keys, exporting and importing them using widely supported formats like PEM or DER.
Curve | Possible identifiers |
---|---|
NIST P-256 | 'NIST P-256' , 'p256' , 'P-256' , 'prime256v1' , 'secp256r1' |
NIST P-384 | 'NIST P-384' , 'p384' , 'P-384' , 'prime384v1' , 'secp384r1' |
NIST P-521 | 'NIST P-521' , 'p521' , 'P-521' , 'prime521v1' , 'secp521r1' |
For more information about each NIST curve see FIPS 186-4, Section D.1.2.
The following example demonstrates how to generate a new ECC key, export it, and subsequently reload it back into the application:
>>> from Crypto.PublicKey import ECC
>>>
>>> key = ECC.generate(curve='P-256')
>>>
>>> f = open('myprivatekey.pem','wt')
>>> f.write(key.export_key(format='PEM'))
>>> f.close()
...
>>> f = open('myprivatekey.pem','rt')
>>> key = ECC.import_key(f.read())
The ECC key can be used to perform or verify ECDSA signatures, using the module
Crypto.Signature.DSS
.
-
class
Crypto.PublicKey.ECC.
EccKey
(**kwargs)¶ Class defining an ECC key. Do not instantiate directly. Use
generate()
,construct()
orimport_key()
instead.Variables: -
export_key
(**kwargs)¶ Export this ECC key.
Parameters: - format (string) –
The format to use for encoding the key:
'DER'
. The key will be encoded in ASN.1 DER format (binary). For a public key, the ASN.1subjectPublicKeyInfo
structure defined in RFC5480 will be used. For a private key, the ASN.1ECPrivateKey
structure defined in RFC5915 is used instead (possibly within a PKCS#8 envelope, see theuse_pkcs8
flag below).'PEM'
. The key will be encoded in a PEM envelope (ASCII).'OpenSSH'
. The key will be encoded in the OpenSSH format (ASCII, public keys only).'SEC1'
. The public key (i.e., the EC point) will be encoded intobytes
according to Section 2.3.3 of SEC1 (which is a subset of the older X9.62 ITU standard).
- passphrase (byte string or string) – The passphrase to use for protecting the private key.
- use_pkcs8 (boolean) –
Only relevant for private keys.
If
True
(default and recommended), the PKCS#8 representation will be used.If
False
, the much weaker PEM encryption mechanism will be used. - protection (string) – When a private key is exported with password-protection
and PKCS#8 (both
DER
andPEM
formats), this parameter MUST be present and be a valid algorithm supported byCrypto.IO.PKCS8
. It is recommended to usePBKDF2WithHMAC-SHA1AndAES128-CBC
. - compress (boolean) –
If
True
, the method returns a more compact representation of the public key, with the X-coordinate only.If
False
(default), the method returns the full public key.
Warning
If you don’t provide a passphrase, the private key will be exported in the clear!
Note
When exporting a private key with password-protection and PKCS#8 (both
DER
andPEM
formats), any extra parameters toexport_key()
will be passed toCrypto.IO.PKCS8
.Returns: A multi-line string (for PEM and OpenSSH) or bytes
(for DER and SEC1) with the encoded key.- format (string) –
-
has_private
()¶ True
if this key can be used for making signatures or decrypting data.
-
-
class
Crypto.PublicKey.ECC.
EccPoint
(x, y, curve='p256')¶ A class to abstract a point over an Elliptic Curve.
The class support special methods for:
- Adding two points:
R = S + T
- In-place addition:
S += T
- Negating a point:
R = -T
- Comparing two points:
if S == T: ...
- Multiplying a point by a scalar:
R = S*k
- In-place multiplication by a scalar:
T *= k
Variables: - x (integer) – The affine X-coordinate of the ECC point
- y (integer) – The affine Y-coordinate of the ECC point
- xy – The tuple with X- and Y- coordinates
-
copy
()¶ Return a copy of this point.
-
double
()¶ Double this point (in-place operation).
Return: EccPoint
: this same object (to enable chaining)
-
is_point_at_infinity
()¶ True
if this is the point-at-infinity.
-
point_at_infinity
()¶ Return the point-at-infinity for the curve this point is on.
-
size_in_bits
()¶ Size of each coordinate, in bits.
-
size_in_bytes
()¶ Size of each coordinate, in bytes.
- Adding two points:
-
exception
Crypto.PublicKey.ECC.
UnsupportedEccFeature
¶
-
Crypto.PublicKey.ECC.
construct
(**kwargs)¶ Build a new ECC key (private or public) starting from some base components.
Parameters: - curve (string) – Mandatory. It must be a curve name defined in Table 1.
- 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.
Returns: a new ECC key object
Return type:
-
Crypto.PublicKey.ECC.
generate
(**kwargs)¶ Generate a new private key on the given curve.
Parameters: - curve (string) – Mandatory. It must be a curve name defined in Table 1.
- randfunc (callable) – Optional. The RNG to read randomness from.
If
None
,Crypto.Random.get_random_bytes()
is used.
-
Crypto.PublicKey.ECC.
import_key
(encoded, passphrase=None, curve_name=None)¶ Import an ECC key (public or private).
Parameters: - encoded (bytes or 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) - A SEC1 (or X9.62) byte string. You must also provide the
curve_name
. - 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 6.5+)
Private keys can be in the clear or password-protected.
- 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.
- curve_name (string) – For a SEC1 byte string only. This is the name of the ECC curve, as defined in Table 1.
Returns: a new ECC key object
Return type: Raises: ValueError
– when the given key cannot be parsed (possibly because the pass phrase is wrong).- encoded (bytes or multi-line string) –