Class JwsSigner
java.lang.Object
com.revetsec.jose.JwsSigner
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classConfigures one signing operation. -
Method Summary
Modifier and TypeMethodDescriptionfromEcKeyPair(@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.fromEd25519KeyPair(@NonNull PrivateKey privateKey, @NonNull PublicKey publicKey) Returns a signer for pure Ed25519 with the fully specifiedEd25519JWS algorithm identifier.fromHeaderAndClaims(@NonNull JwtSigningHeader header, @NonNull JwtClaimsSet claims) Signs the header metadata and outbound claims with the default two-second operation budget, returning a compact JWT credential.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.Returns the one selected signing algorithm.Returns the stable, inspectable checked public projection.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.toString()Returns a description without key or credential contents.voidExplicitly signs and verifies a fixed internal noncredential probe without returning a credential.withHeaderAndClaims(@NonNull JwtSigningHeader header, @NonNull JwtClaimsSet claims) Starts a signing builder with the required protected-header metadata and outbound claims.
-
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 encodingpublicKey- the inspectable RSA public key, snapshotted without encodingalgorithm- exactly PS256, PS384, PS512, RS256, RS384 or RS512- Returns:
- the signer
- Throws:
NullPointerException- if a required argument is nullIllegalArgumentException- 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 encodingpublicKey- the inspectable EC public key, snapshotted without encodingalgorithm- exactly ES256 or ES384- Returns:
- the signer
- Throws:
NullPointerException- if a required argument is nullIllegalArgumentException- 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 specifiedEd25519JWS 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 exposesEdECKeyparameters, 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. LegacyEdDSAis not emitted.- Parameters:
privateKey- the application-owned private key, retained by reference without encodingpublicKey- the inspectable Ed25519 public key, snapshotted without encoding- Returns:
- the signer using
JwsAlgorithm.ED25519 - Throws:
NullPointerException- if a required argument is nullIllegalArgumentException- 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
@CheckReturnValue public @NonNull JwsSigner.Builder withHeaderAndClaims(@NonNull JwtSigningHeader header, @NonNull JwtClaimsSet claims) Starts a signing builder with the required protected-header metadata and outbound claims. Construction does not serialize claims or invoke a provider. The builder'sJwsSigner.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 metadataclaims- 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
@CheckReturnValue public @NonNull String fromHeaderAndClaims(@NonNull JwtSigningHeader header, @NonNull JwtClaimsSet claims) Signs the header metadata and outbound claims with the default two-second operation budget, returning a compact JWT credential. Equivalent towithHeaderAndClaims(header, claims).build(). The algorithm comes from this signer, and the claims' application meaning remains the caller's responsibility.- Parameters:
header- the required header metadataclaims- the required outbound claims- Returns:
- the verified compact JWT credential; keep it out of logs
- Throws:
NullPointerException- if a required argument is nullIllegalArgumentException- if the serialized claims exceed the signing JSON profile or size limitsJwsSigningException- 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+jwtkeyId- a nonempty key identifier of at most 256 characters, or null for nonecertificateSha256Thumbprint- exactly 32 bytes, SHA-256 of a DER certificate, or null for noneclaimsUtf8- strict UTF-8 JSON object bytes; the accepted bytes are signed without reserializationremainingBudget- 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 nullIllegalArgumentException- if a supplied type, identifier, digest or claims input is invalidJwsSigningException- if signing, pair verification or the remaining budget fails- Since:
- 1.0.0
-
warmUp
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 nullJwsSigningException- if signing, pair verification or the budget fails- Since:
- 1.0.0
-
toString
-