# Edwards-curve Digital Signature Algorithm (EdDSA)

EdDSA is a deterministic digital signature scheme based on twisted Edwards elliptic curves (Ed25519 and Ed448). It is specified in RFC8032, as two variants:

- PureEdDSA, where the message is signed directly.

- HashEdDSA, where the message is first hashed, and only the resulting digest is signed. This should only be used by streaming applications because it avoids double passes on messages, at the cost of reduced collision resistance.

This module supports signatures for both variants (PureEdDSA and HashEdDSA), on the Ed25519 curve (with a 128-bit security level), and on the Ed448 curve (with a 224-bit security level).

For HashEdDSA, the hash function must be SHA-512 in case of Ed25519, and SHAKE256 for Ed448.

A sender can use a private key (loaded from a file) to sign a message:

    from Crypto.PublicKey import ECC
    from Signature import eddsa

    message = b'I give my permission to order #4355'
    key = ECC.import_key(open("private_ed25519.pem").read()))
    signer = eddsa.new(key, 'rfc8032')
    signature = signer.sign(message)

The receiver can use the matching public key to verify authenticity of the received message:

    from Crypto.PublicKey import ECC
    from Signature import eddsa

    message = b'I give my permission to order #4355'
    key = ECC.import_key(open("public_ed25519.pem").read()))
    verifier = eddsa.new(key, 'rfc8032')
    try:
        verifier.verify(message, signature)
        print("The message is authentic")
    except ValueError:
        print("The message is not authentic")

Alternatively the HashedEdDSA variant can be used to sign a message with Ed25519:

    from Crypto.PublicKey import ECC
    from Signature import eddsa
    from Crypto.Hash import SHA512

    message = b'I give my permission to order #4355'
    prehashed_message = SHA512.new(message)
    key = ECC.import_key(open("private_ed25519.pem").read()))
    signer = eddsa.new(key, 'rfc8032')
    signature = signer.sign(prehashed_message)

HashedEdDSA also exists for Ed448:

    from Crypto.PublicKey import ECC
    from Signature import eddsa
    from Crypto.Hash import SHAKE256

    message = b'I give my permission to order #4355'
    prehashed_message = SHAKE256.new(message)
    key = ECC.import_key(open("private_ed448.pem").read()))
    signer = eddsa.new(key, 'rfc8032')
    signature = signer.sign(prehashed_message)

class Crypto.Signature.eddsa.EdDSASigScheme(key, context)

  An EdDSA signature object. Do not instantiate directly. Use `Crypto.Signature.eddsa.new()`.

  can_sign()

    Return `True` if this signature object can be used for signing messages.

  sign(msg_or_hash)

    Compute the EdDSA signature of a message.

    Parameters:

      msg_or_hash (bytes or a hash object) –

      The message to sign (`bytes`, in case of PureEdDSA) or the hash that was carried out over the message (hash object, for HashEdDSA).

      The hash object must be `Crypto.Hash.SHA512` for Ed25519, and `Crypto.Hash.SHAKE256` object for Ed448.

    Returns:

      The signature as `bytes`. It is always 64 bytes for Ed25519, and 114 bytes for Ed448.

    Raises:

      TypeError – if the EdDSA key has no private half

  verify(msg_or_hash, signature)

    Check if an EdDSA signature is authentic.

    Parameters:

      - msg_or_hash (bytes or a hash object) –

        The message to verify (`bytes`, in case of PureEdDSA) or the hash that was carried out over the message (hash object, for HashEdDSA).

        The hash object must be `Crypto.Hash.SHA512` object for Ed25519, and `Crypto.Hash.SHAKE256` for Ed448.

      - signature (`bytes`) – The signature that needs to be validated. It must be 64 bytes for Ed25519, and 114 bytes for Ed448.

    Raises:

      ValueError – if the signature is not authentic

Crypto.Signature.eddsa.import_private_key(encoded)

  Create a new Ed25519 or Ed448 private key object, starting from the key encoded as raw `bytes`, in the format described in RFC8032.

  Parameters:

    encoded (bytes) – The EdDSA private key to import. It must be 32 bytes for Ed25519, and 57 bytes for Ed448.

  Returns:

    a new ECC key object.

  Return type:

    `Crypto.PublicKey.EccKey`

  Raises:

    ValueError – when the given key cannot be parsed.

Crypto.Signature.eddsa.import_public_key(encoded)

  Create a new Ed25519 or Ed448 public key object, starting from the key encoded as raw `bytes`, in the format described in RFC8032.

  Parameters:

    encoded (bytes) – The EdDSA public key to import. It must be 32 bytes for Ed25519, and 57 bytes for Ed448.

  Returns:

    a new ECC key object.

  Return type:

    `Crypto.PublicKey.EccKey`

  Raises:

    ValueError – when the given key cannot be parsed.

Crypto.Signature.eddsa.new(key, mode, context=None)

  Create a signature object `EdDSASigScheme` that can perform or verify an EdDSA signature.

  Parameters:

    - key (`Crypto.PublicKey.ECC` object) – The key to use for computing the signature (private keys only) or for verifying one. The key must be on the curve `Ed25519` or `Ed448`.

    - mode (string) – This parameter must be `'rfc8032'`.

    - context (bytes) – Up to 255 bytes of context, which is a constant byte string to segregate different protocols or different applications of the same key.