Class JwsSigner

java.lang.Object
com.revetsec.jose.JwsSigner

@ThreadSafe public final class JwsSigner extends Object
Signs compact JWS credentials with one application-owned key pair and one fixed algorithm. PS256, PS384, PS512, RS256, RS384, RS512, ES256, ES384 and Ed25519 are supported. Each operation uses fresh JCA engines and verifies its actual signature against the checked public projection before releasing any credential. Provider selection is left to JCA; no fallback or provider configuration change is made.

The private key is retained by reference, may be opaque or nonexportable, and is never encoded or returned. Applications own its persistent storage, registration and rotation. Construction makes structural checks only: it never signs, probes the pair or invokes a JCA provider. Explicit warmUp(Duration) probes the pair without creating a credential.

Operations run on the caller thread and measure their remaining budget with monotonic time. They discard late output but cannot preempt a trusted provider that hangs: bounded completion requires cooperative providers. Callers also check their original deadline after this operation. No thread or executor is owned by the signer.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • fromRsaKeyPair

      @CheckReturnValue public static @NonNull JwsSigner fromRsaKeyPair(@NonNull PrivateKey privateKey, @NonNull PublicKey publicKey, @NonNull JwsAlgorithm algorithm)
      Returns a signer after bounded structural checks of its algorithm and inspectable RSA public projection. Public keys must satisfy the existing 2048–16384-bit, exponent and ROCA policy. RSA-PSS key restrictions are preserved; a PSS-only key cannot be selected for RS256, RS384 or RS512. This factory does not test pair agreement.
      Parameters:
      privateKey - the application-owned private key, retained by reference without encoding
      publicKey - the inspectable RSA public key, snapshotted without encoding
      algorithm - exactly PS256, PS384, PS512, RS256, RS384 or RS512
      Returns:
      the signer
      Throws:
      NullPointerException - if a required argument is null
      IllegalArgumentException - if a supplied algorithm or key is structurally invalid or unsupported
      Since:
      1.0.0
    • fromEcKeyPair

      @CheckReturnValue public static @NonNull JwsSigner fromEcKeyPair(@NonNull PrivateKey privateKey, @NonNull PublicKey publicKey, @NonNull JwsAlgorithm algorithm)
      Returns a signer after bounded structural checks of an EC public point and its complete domain parameters. ES256 requires exactly P-256; ES384 requires exactly P-384. The optional domain seed is not significant. The private key must report EC and may remain opaque. This factory does not invoke JCA or test pair agreement; each signing operation verifies its actual signature against the independent public snapshot before release.
      Parameters:
      privateKey - the application-owned EC private key, retained by reference without encoding
      publicKey - the inspectable EC public key, snapshotted without encoding
      algorithm - exactly ES256 or ES384
      Returns:
      the signer
      Throws:
      NullPointerException - if a required argument is null
      IllegalArgumentException - if the algorithm, public point or domain parameters are unsupported or invalid
      Since:
      1.0.0
    • fromEd25519KeyPair

      @CheckReturnValue public static @NonNull JwsSigner fromEd25519KeyPair(@NonNull PrivateKey privateKey, @NonNull PublicKey publicKey)
      Returns a signer for pure Ed25519 with the fully specified Ed25519 JWS algorithm identifier. The public key must name Ed25519 and its bounded point must decode canonically and not have small order. Its point and parameters are snapshotted without encoding. The private key may remain opaque and must report Ed25519 or EdDSA; if it exposes EdECKey parameters, those must name Ed25519. Private key bytes are never read. Construction invokes no JCA provider or signing probe; every actual operation verifies its signature against the checked public snapshot before release. Legacy EdDSA is not emitted.
      Parameters:
      privateKey - the application-owned private key, retained by reference without encoding
      publicKey - the inspectable Ed25519 public key, snapshotted without encoding
      Returns:
      the signer using JwsAlgorithm.ED25519
      Throws:
      NullPointerException - if a required argument is null
      IllegalArgumentException - if a supplied key or inspectable parameter is structurally invalid or unsupported
      Since:
      1.0.0
    • getAlgorithm

      Returns the one selected signing algorithm.
      Returns:
      the selected signing algorithm
      Since:
      1.0.0
    • getPublicKey

      Returns the stable, inspectable checked public projection. It does not expose private material, and its encoding and format are absent; applications retain their original public key when an encoded key is needed.
      Returns:
      the checked public key
      Since:
      1.0.0
    • withHeaderAndClaims

      Starts a signing builder with the required protected-header metadata and outbound claims. Construction does not serialize claims or invoke a provider. The builder's JwsSigner.Builder.build() signs and returns a compact JWT, using a two-second operation budget unless overridden. The algorithm always comes from this signer.
      Parameters:
      header - the required header metadata
      claims - the required outbound claims; construction does not establish that they are trusted or valid
      Returns:
      a new signing builder
      Throws:
      NullPointerException - if a required argument is null
      Since:
      1.0.0
    • fromHeaderAndClaims

      Signs the header metadata and outbound claims with the default two-second operation budget, returning a compact JWT credential. Equivalent to withHeaderAndClaims(header, claims).build(). The algorithm comes from this signer, and the claims' application meaning remains the caller's responsibility.
      Parameters:
      header - the required header metadata
      claims - the required outbound claims
      Returns:
      the verified compact JWT credential; keep it out of logs
      Throws:
      NullPointerException - if a required argument is null
      IllegalArgumentException - if the serialized claims exceed the signing JSON profile or size limits
      JwsSigningException - if signing, pair verification or the operation budget fails
      Since:
      1.0.0
    • toCompactSerialization

      @CheckReturnValue public @NonNull String toCompactSerialization(@NonNull String type, @Nullable String keyId, byte @Nullable [] certificateSha256Thumbprint, byte @NonNull [] claimsUtf8, @NonNull Duration remainingBudget)
      Signs the exact accepted UTF-8 claims bytes and returns a compact JWS credential, an explicit secret emission. Claims are one strict JSON object under the existing JOSE defaults, limited to 32 KiB; their semantics belong to the caller. Arrays are snapshotted after length checks. The fixed protected header holds only alg, typ and optional kid/x5t#S256, is limited to 4 KiB encoded, and the final compact credential to 64 KiB.
      Parameters:
      type - exactly client-authentication+jwt, JWT or at+jwt
      keyId - a nonempty key identifier of at most 256 characters, or null for none
      certificateSha256Thumbprint - exactly 32 bytes, SHA-256 of a DER certificate, or null for none
      claimsUtf8 - strict UTF-8 JSON object bytes; the accepted bytes are signed without reserialization
      remainingBudget - the caller's remaining monotonic budget; nonpositive values are exhausted
      Returns:
      the verified compact JWS credential; keep it out of logs
      Throws:
      NullPointerException - if a required argument is null
      IllegalArgumentException - if a supplied type, identifier, digest or claims input is invalid
      JwsSigningException - if signing, pair verification or the remaining budget fails
      Since:
      1.0.0
    • warmUp

      public void warmUp(@NonNull Duration remainingBudget)
      Explicitly signs and verifies a fixed internal noncredential probe without returning a credential. It runs on the caller thread; trusted providers must cooperate with the budget (see the class description).
      Parameters:
      remainingBudget - the caller's remaining monotonic budget
      Throws:
      NullPointerException - if remainingBudget is null
      JwsSigningException - if signing, pair verification or the budget fails
      Since:
      1.0.0
    • toString

      Returns a description without key or credential contents.
      Overrides:
      toString in class Object
      Returns:
      the redacted description
      Since:
      1.0.0