> For the complete documentation index, see [llms.txt](https://docs.corppass.gov.sg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corppass.gov.sg/technical-specifications/technical-concepts/jws-and-jwe.md).

# JWS and JWE

Corppass leverages **JWS (JSON Web Signature)** and **JWE (JSON Web Encryption)** to securely exchange and verify sensitive authorization data between clients and the authorization server.

These mechanisms align with [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515.html) (JWS) and [RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516) (JWE), and are used to ensure **integrity**, **authenticity**, and **confidentiality** of data in the Corppass authorization flow.

{% hint style="warning" %}
Corppass **strongly recommends** clients to use **libraries** to handle JWTs instead of attempting it themselves. 

See [here](https://www.jwt.io/libraries) for an overview of JWT libraries that clients can use to do so.
{% endhint %}

## JSON Web Signature (JWS)

JWS ensures the **integrity** and **authenticity** of data by digitally signing it. It is used to protect critical tokens like client assertions and ID tokens from tampering.

A JWS consists of three components, each Base64URL-encoded and concatenated with periods (`.`):

1. **Header** – Contains metadata such as the signing algorithm (`alg`) and key identifier (`kid`).
2. **Payload** – The data or claims being signed (e.g., client ID, token expiry).
3. **Signature** – A cryptographic signature generated using the sender’s private key.

```markup
<base64url-encoded header>.<base64url-encoded payload>.<base64url-encoded signature>
```

### Usage in Corppass

JWS is used to sign JWTs in the following scenarios:

* **Client Assertion JWTs:** Relying Parties (RPs) send signed JWT `client_assertion` to authenticate themselves.
* **ID Tokens:** Corppass signs the ID Tokens to assert that the payload is authentic and not tampered with.

Corppass verifies these signatures using the public keys provided via the client’s JWKS.

### JWS Header Example

```json
{
  "typ": "JWT",
  "alg": "ES256", 
  "kid": "d591e152-886e-46cc-aa70-36a4431162a6"
}
```

<table><thead><tr><th width="161.2890625">Field</th><th>Description</th></tr></thead><tbody><tr><td>typ</td><td>Type of object (<code>JWT</code>).</td></tr><tr><td>alg</td><td>The algorithm used for signing the JWT.</td></tr><tr><td>kid</td><td>Key ID, used to locate the corresponding public key in the client’s JWKS.</td></tr></tbody></table>

## JSON Web Encryption (JWE)

**JWE** ensures the **confidentiality** of data by encrypting it, ensuring that only the intended recipient (the RP) can decrypt and read the content.

A JWE consists of five components, each Base64URL-encoded and concatenated with periods (`.`):

1. **Protected Header**: Contains metadata about the encryption algorithm (`alg`) and encryption key.
2. **Encrypted Key**: The key used to encrypt the payload.
3. **Initialisation Vector (IV)**: Ensures randomness in encryption.
4. **Cipher Text**: The encrypted payload.
5. **Authentication Tag**: Ensures integrity of the encrypted data.

```
<Protected Header>.<Encrypted Key>.<IV>.<Ciphertext>.<Authentication Tag>
```

### Usage in Corppass

JWE is used to encrypt a signed JWT (JWS) in the following scenarios:

* **ID Token:** The ID token is issued as a **Signed JWT (JWS: JSON Web Signature)** and subsequently encrypted using the RP’s public key to produce a **JWE**.
* **User Info Payload:** The response payload from the `/userinfo` endpoint is issued as a **Signed JWT (JWS: JSON Web Signature)** and subsequently encrypted using the RP’s public key to produce a **JWE**.

### JWE Protected Header

<table><thead><tr><th width="199.12890625">Field</th><th>Description</th></tr></thead><tbody><tr><td>typ</td><td>Type of token, usually <code>JWT</code>. Helps distinguish JWTs from other data types.</td></tr><tr><td>alg</td><td>The key management algorithm used to encrypt the key that encrypts the payload.</td></tr><tr><td>kid</td><td>Key ID used to identify which public key in the RP's JWKS should be used to perform encryption.</td></tr><tr><td>enc</td><td>Content encryption algorithm. Corppass may use <code>A256GCM</code> (AES-GCM with 256-bit key).</td></tr></tbody></table>

{% hint style="warning" %}
JWE supports both symmetric and asymmetric encryption algorithms. Corppass only supports **asymmetric key pairs** that use **Elliptic Curve (EC)-based key agreement algorithms** to determine a common encryption key, specifically:

* `ECDH-ES+A128KW`
* `ECDH-ES+A256KW`
* `ECDH-ES+A512KW`

These algorithms use **Elliptic Curve Diffie-Hellman (ECDH)** for key agreement and **AES Key Wrapping (AxxxKW)** for content encryption.
{% endhint %}

{% hint style="warning" %}
Clients **must** use the **`kid`** field in the JWE header to identify the client's public key, used by Corppass for encryption.
{% endhint %}

Refer to [RFC 7515 Section 4](https://tools.ietf.org/html/rfc7515#section-4) for more information about the JWE structure.

#### Sample JWE Header

```json
{
  "typ": "JWT",
  "alg": "ECDH-ES+A256KW", 
  "kid": "nxiJJNNVxxnTkU2wL65TI2PkILIJOURSTQSABLuH2kE", 
  "enc": "A256CBC-HS512"
}
```