# 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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corppass.gov.sg/technical-specifications/technical-concepts/jws-and-jwe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.