org.bouncycastle.crypto.signers

## Class PSSSigner

- java.lang.Object
- - org.bouncycastle.crypto.signers.PSSSigner

- All Implemented Interfaces:
    Signer

      public class PSSSigner
      extends java.lang.Object
      implements Signer

  RSA-PSS as described in PKCS# 1 v 2.1.

  Note: the usual value for the salt length is the number of bytes in the hash function.

  The `createRawSigner(AsymmetricBlockCipher, Digest)` family builds a signer that operates on a pre-computed message hash (mHash) rather than the message itself. RFC 8017 (PKCS#1 v2.2) sec. 9.1 EMSA-PSS first hashes the message M to mHash and then salts and re-hashes; these factories replace only that first hash with a `Prehash` pass-through, so the caller supplies mHash via `update(...)` and the signer still performs the salt / M' / second-hash / masking steps. The bytes supplied must be exactly the content digest's output length, otherwise signing or verification fails with "Incorrect prehash size". This is the lightweight-API equivalent of a "sign/verify pre-computed hash" entry point (github #1145). See `org.bouncycastle.crypto.examples.RSAPSSPreComputedHashExample`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `TRAILER_IMPLICIT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PSSSigner(AsymmetricBlockCipher cipher, Digest digest, byte[] salt)`
    `PSSSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, byte[] salt)`
    `PSSSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, byte[] salt, byte trailer)`
    `PSSSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, int sLen)`
    `PSSSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, int sLen, byte trailer)`
    `PSSSigner(AsymmetricBlockCipher cipher, Digest digest, int sLen)` basic constructor
    `PSSSigner(AsymmetricBlockCipher cipher, Digest digest, int sLen, byte trailer)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PSSSigner` | `createRawSigner(AsymmetricBlockCipher cipher, Digest digest)` Create a PSS signer/verifier that consumes a pre-computed message hash.
    `static PSSSigner` | `createRawSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, byte[] salt, byte trailer)` Create a PSS signer/verifier that consumes a pre-computed message hash, using a fixed salt (chiefly for known-answer testing where the salt must be reproducible).
    `static PSSSigner` | `createRawSigner(AsymmetricBlockCipher cipher, Digest contentDigest, Digest mgfDigest, int sLen, byte trailer)` Create a PSS signer/verifier that consumes a pre-computed message hash, with the MGF digest, salt length and trailer specified explicitly.
    `byte[]` | `generateSignature()` generate a signature for the message we've been loaded with using the key we were initialised with.
    `void` | `init(boolean forSigning, CipherParameters param)` Initialise the signer for signing or verification.
    `void` | `reset()` reset the internal state
    `void` | `update(byte b)` update the internal digest with the byte b
    `void` | `update(byte[] in, int off, int len)` update the internal digest with the byte array in
    `boolean` | `verifySignature(byte[] signature)` return true if the internal state represents the signature described in the passed in array.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TRAILER_IMPLICIT

          public static final byte TRAILER_IMPLICIT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest digest,
                           int sLen)

      basic constructor
      Parameters:
        `cipher` - the asymmetric cipher to use.
        `digest` - the digest to use.
        `sLen` - the length of the salt to use (in bytes).

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest contentDigest,
                           Digest mgfDigest,
                           int sLen)

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest digest,
                           int sLen,
                           byte trailer)

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest contentDigest,
                           Digest mgfDigest,
                           int sLen,
                           byte trailer)

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest digest,
                           byte[] salt)

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest contentDigest,
                           Digest mgfDigest,
                           byte[] salt)

    - #### PSSSigner

          public PSSSigner(AsymmetricBlockCipher cipher,
                           Digest contentDigest,
                           Digest mgfDigest,
                           byte[] salt,
                           byte trailer)

  - ### Method Detail

    - #### createRawSigner

          public static PSSSigner createRawSigner(AsymmetricBlockCipher cipher,
                                                  Digest digest)

      Create a PSS signer/verifier that consumes a pre-computed message hash. The caller feeds exactly `digest.getDigestSize()` bytes (the hash of the message under `digest`) through `update(...)` before `generateSignature()` / `verifySignature(...)`; `digest` is also used for the EMSA-PSS second hash and the MGF1 mask, and the salt length defaults to the digest output length with the implicit (0xBC) trailer.
      Parameters:
        `cipher` - the asymmetric cipher to use (e.g. a configured RSAEngine).
        `digest` - the digest the supplied hash was produced with.

    - #### createRawSigner

          public static PSSSigner createRawSigner(AsymmetricBlockCipher cipher,
                                                  Digest contentDigest,
                                                  Digest mgfDigest,
                                                  int sLen,
                                                  byte trailer)

      Create a PSS signer/verifier that consumes a pre-computed message hash, with the MGF digest, salt length and trailer specified explicitly. The caller feeds exactly `contentDigest.getDigestSize()` bytes (the pre-computed hash) through `update(...)`; `contentDigest` performs the EMSA-PSS second hash and `mgfDigest` drives the MGF1 mask.
      Parameters:
        `cipher` - the asymmetric cipher to use.
        `contentDigest` - the digest the supplied hash was produced with, also used for the second hash.
        `mgfDigest` - the digest to use for the MGF1 mask generation function.
        `sLen` - the length of the salt to use (in bytes).
        `trailer` - the trailer byte (usually `TRAILER_IMPLICIT`).

    - #### createRawSigner

          public static PSSSigner createRawSigner(AsymmetricBlockCipher cipher,
                                                  Digest contentDigest,
                                                  Digest mgfDigest,
                                                  byte[] salt,
                                                  byte trailer)

      Create a PSS signer/verifier that consumes a pre-computed message hash, using a fixed salt (chiefly for known-answer testing where the salt must be reproducible). The caller feeds exactly `contentDigest.getDigestSize()` bytes (the pre-computed hash) through `update(...)`.
      Parameters:
        `cipher` - the asymmetric cipher to use.
        `contentDigest` - the digest the supplied hash was produced with, also used for the second hash.
        `mgfDigest` - the digest to use for the MGF1 mask generation function.
        `salt` - the fixed salt to use.
        `trailer` - the trailer byte (usually `TRAILER_IMPLICIT`).

    - #### init

          public void init(boolean forSigning,
                           CipherParameters param)

      Description copied from interface: `Signer`
      Initialise the signer for signing or verification.
      Specified by:
        `init` in interface `Signer`
      Parameters:
        `forSigning` - true if for signing, false otherwise
        `param` - necessary parameters.

    - #### update

          public void update(byte b)

      update the internal digest with the byte b
      Specified by:
        `update` in interface `Signer`

    - #### update

          public void update(byte[] in,
                             int off,
                             int len)

      update the internal digest with the byte array in
      Specified by:
        `update` in interface `Signer`

    - #### reset

          public void reset()

      reset the internal state
      Specified by:
        `reset` in interface `Signer`

    - #### generateSignature

          public byte[] generateSignature()
                                   throws CryptoException,
                                          DataLengthException

      generate a signature for the message we've been loaded with using the key we were initialised with.
      Specified by:
        `generateSignature` in interface `Signer`
      Throws:
        `CryptoException`
        `DataLengthException`

    - #### verifySignature

          public boolean verifySignature(byte[] signature)

      return true if the internal state represents the signature described in the passed in array.
      Specified by:
        `verifySignature` in interface `Signer`