Signature API

## What a digital signature is (plain terms) A **digital signature** answers two questions about a piece of data: *did it really come from the holder of a specific private key* (authenticity) and *was it changed since it was signed* (integrity). It works with a **key pair**: a **private key** that only the signer holds, and a **public key** that anyone can have. The signer uses the private key to produce a signature; anyone with the public key can check it. The private key cannot be derived from the public key. ## The Java class: java.security.Signature Java's cryptography is built on the **JCA (Java Cryptography Architecture)** — a provider-based framework where you ask for an engine *by name* and a provider supplies the implementation. The signing engine is `java.security.Signature`. You never call `new Signature()`; you call the factory method: ```java Signature sig = Signature.getInstance("SHA256withRSA"); ``` The string `"SHA256withRSA"` is the **algorithm name**. Read it as "hash the data with SHA-256, then sign that hash with RSA". Other common ones: `"SHA256withECDSA"` (elliptic-curve), `"SHA512withRSA"`, `"SHA256withDSA"`. The hash part and the key-algorithm part both matter and the key-algorithm part **must match the key you use**. ## The two lifecycles A `Signature` object is a small state machine. After `getInstance` it is **uninitialized**; you choose a direction by initializing it: **Signing (you hold the private key):** 1. `sig.initSign(privateKey)` — puts the object into SIGN state. 2. `sig.update(bytes)` — feed the data to be signed. You may call this many times; the data is accumulated. Order matters. 3. `byte[] signature = sig.sign()` — internally hashes all the fed data and produces the signature bytes using the private key. After `sign()` the object resets and can be reused for another signature. **Verifying (you hold the public key):** 1. `sig.initVerify(publicKey)` — puts the object into VERIFY state. 2. `sig.update(bytes)` — feed **exactly the same bytes**, in the same order, that were signed. 3. `boolean ok = sig.verify(signature)` — returns `true` if the signature was produced by the matching private key over exactly this data, `false` otherwise. **It returns a boolean; it does not throw on a bad signature** (it throws `SignatureException` only on malformed input). ## Where the keys come from Keys are produced by a `KeyPairGenerator`: ```java KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA"); kpg.initialize(2048); KeyPair kp = kpg.generateKeyPair(); PrivateKey priv = kp.getPrivate(); PublicKey pub = kp.getPublic(); ``` `getPrivate()` feeds `initSign`; `getPublic()` feeds `initVerify`. The signer keeps the private key secret and publishes the public key. ## A complete round-trip ```java byte[] data = "hello".getBytes(StandardCharsets.UTF_8); Signature signer = Signature.getInstance("SHA256withRSA"); signer.initSign(kp.getPrivate()); signer.update(data); byte[] signature = signer.sign(); Signature verifier = Signature.getInstance("SHA256withRSA"); verifier.initVerify(kp.getPublic()); verifier.update(data); boolean valid = verifier.verify(signature); // true ``` If even one byte of `data` differs between signing and verifying, `verify` returns `false`. If the wrong public key is used, it returns `false`. ## Checked exceptions you must handle `getInstance` throws `NoSuchAlgorithmException`; `initSign`/`initVerify` throw `InvalidKeyException` (e.g., an EC key with an RSA algorithm); `update`/`sign`/`verify` throw `SignatureException` (object in the wrong state or malformed signature input). These are checked exceptions. ## Mental model Think of `Signature` as a one-track tape recorder: you press SIGN or VERIFY (init), play the tape through (update), and then either burn a seal (`sign`) or check the seal (`verify`).