# PKCS#1 PSS (RSA)

A probabilistic digital signature scheme based on RSA.

It is more formally called `RSASSA-PSS` in Section 8.1 of RFC8017.

The following example shows how the sender can use its own private key (loaded from a file) to create the signature of a message:

    >>> from Crypto.Signature import pss
    >>> from Crypto.Hash import SHA256
    >>> from Crypto.PublicKey import RSA
    >>>
    >>> message = b'To be signed'
    >>> key = RSA.import_key(open('privkey.der', 'rb').read())
    >>> h = SHA256.new(message)
    >>> signature = pss.new(key).sign(h)

At the receiver side, the matching public RSA key is used to verify authenticity of the incoming message:

    >>> key = RSA.import_key(open('pubkey.der', 'rb').read())
    >>> h = SHA256.new(message)
    >>> verifier = pss.new(key)
    >>> try:
    >>>     verifier.verify(h, signature)
    >>>     print("The signature is authentic.")
    >>> except (ValueError):
    >>>     print("The signature is not authentic.")

Crypto.Signature.pss.MGF1(mgfSeed, maskLen, hash_gen)

  Mask Generation Function, described in B.2.1 of RFC8017.

  Parameters:

    - mfgSeed (byte string) – seed from which the mask is generated

    - maskLen (integer) – intended length in bytes of the mask

    - hash_gen – A module or a hash object from `Crypto.Hash`

  Returns:

    the mask, as a byte string

class Crypto.Signature.pss.PSS_SigScheme(key, mgfunc, saltLen, randfunc)

  A signature object for `RSASSA-PSS`. Do not instantiate directly. Use `Crypto.Signature.pss.new()`.

  can_sign()

    Return `True` if this object can be used to sign messages.

  sign(msg_hash)

    Create the PKCS#1 PSS signature of a message.

    This function is also called `RSASSA-PSS-SIGN` and it is specified in section 8.1.1 of RFC8017.

    Parameters:

      msg_hash (hash object) – This is an object from the `Crypto.Hash` package. It has been used to digest the message to sign.

    Returns:

      the signature encoded as a byte string.

    Raises:

      - ValueError – if the RSA key is not long enough for the given hash algorithm.

      - TypeError – if the RSA key has no private half.

  verify(msg_hash, signature)

    Check if the PKCS#1 PSS signature over a message is valid.

    This function is also called `RSASSA-PSS-VERIFY` and it is specified in section 8.1.2 of RFC8037.

    Parameters:

      - msg_hash – The hash that was carried out over the message. This is an object belonging to the `Crypto.Hash` module.

      - signature (bytes) – The signature that needs to be validated.

    Raises:

      ValueError – if the signature is not valid.

Crypto.Signature.pss.new(rsa_key, **kwargs)

  Create an object for making or verifying PKCS#1 PSS signatures.

  Parameters:

    rsa_key (RSA object) – The RSA key to use for signing or verifying the message. This is a `Crypto.PublicKey.RSA` object. Signing is only possible when `rsa_key` is a private RSA key.

  Keyword Arguments:

    - mask_func (`callable`) – A function that returns the mask (as bytes). It must accept two parameters: a seed (as bytes) and the length of the data to return.

      If not specified, it will be the function `MGF1()` defined in RFC8017 and combined with the same hash algorithm applied to the message to sign or verify.

      If you want to use a different function, for instance still `MGF1()` but together with another hash, you can do:

          from Crypto.Hash import SHA256
          from Crypto.Signature.pss import MGF1
          mgf = lambda x, y: MGF1(x, y, SHA256)

    - salt_bytes (`integer`) – Length of the salt, in bytes. It is a value between 0 and `emLen - hLen - 2`, where `emLen` is the size of the RSA modulus and `hLen` is the size of the digest applied to the message to sign or verify.

      The salt is generated internally, you don’t need to provide it.

      If not specified, the salt length will be `hLen`. If it is zero, the signature scheme becomes deterministic.

      Note that in some implementations such as OpenSSL the default salt length is `emLen - hLen - 2` (even though it is not more secure than `hLen`).

    - rand_func (`callable`) – A function that returns random `bytes`, of the desired length. The default is `Crypto.Random.get_random_bytes()`.

  Returns:

    a `PSS_SigScheme` signature object