> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/security/cryptographic-guarantees.md).

# Cryptographic guarantees

Oomus CampaignID integrates cryptographic guarantees at every stage of the card lifecycle — from generation to offline verification. This page describes these guarantees from a functional perspective.

***

## Uniqueness — Base36 Identifiers

Each card generated by Oomus CampaignID receives a **unique identifier** produced by a cryptographically secure random number generator (**CSPRNG**).

### Properties

* **Format** : Base36 (digits 0–9 + letters A–Z)
* **Length** : 8 characters
* **Collision** : practically impossible within the scope of a campaign

### Guarantees

| Property              | Guarantee                                                  |
| --------------------- | ---------------------------------------------------------- |
| **Unpredictability**  | Impossible to guess the next generated identifier          |
| **Uniqueness**        | Each identifier is unique within the context of a campaign |
| **Human readability** | Short alphanumeric format, easily entered by a field agent |

The MPI identifier follows the same Base36 logic for its unique segment (`9XQ7LM2A`).

***

## Integrity — AES-256-GCM Encryption

Sensitive verification data is protected by **AES-256-GCM authenticated encryption** (Advanced Encryption Standard, Galois/Counter Mode).

### Why AES-256-GCM?

AES-256-GCM provides two properties at the same time:

* **Confidentiality** : encrypted data is unreadable without the key
* **Authenticity** : any tampered ciphertext is detected immediately (GCM authentication tag)

This means that any attempt to falsify the encrypted data is detectable, not just unreadable.

***

## Auditability — SHA-256 Hash Chain

Oomus CampaignID maintains a **SHA-256 hash chain** that links each audit entry to the previous one, forming an immutable chain. Each block includes a cryptographic link to the previous block, making retrospective tampering detectable.

### Guarantees

| Property             | Guarantee                                                    |
| -------------------- | ------------------------------------------------------------ |
| **Immutability**     | Modifying a past entry invalidates all subsequent blocks     |
| **Tamper detection** | Any manipulation of the chain is detectable                  |
| **Non-repudiation**  | Each action is irrefutably linked to its actor and timestamp |

The audit chain is also used to link the verification portal log to the generation audit.

***

## Offline verification — WebCrypto API

Offline card verification uses the**WebCrypto API** native to modern browsers (W3C standard).

### WebCrypto benefits

| Property            | Benefit                                                  |
| ------------------- | -------------------------------------------------------- |
| **Browser-native**  | No plugin, no app to install                             |
| **Local execution** | No data leaves the device during verification            |
| **W3C standard**    | Available on Chrome, Firefox, Safari, Edge (all devices) |
| **Performance**     | Instant verification                                     |

### Verification process

```
Card code or QR token scanned
          │
          ▼
Cryptographic derivation in the browser (WebCrypto)
          │
          ▼
Lookup in the local registry
          │
          ├─ Entry found, status = "valid"   → Authentic card
          ├─ Entry found, status = "revoked" → Revoked card
          └─ Not found → Unknown / potentially forged card
```

***

## Opaque QR token — Non-reversibility

The QR code printed on each card contains a **non-reversible opaque token**.

### Token properties

| Property              | Description                                                                     |
| --------------------- | ------------------------------------------------------------------------------- |
| **Opacity**           | The token contains no decipherable information without the server key           |
| **Non-reversibility** | It is impossible to recover the MPI ID or the beneficiary's name from the token |
| **Uniqueness**        | One token per card — two cards for the same beneficiary have different tokens   |
| **Verifiability**     | The server can confirm validity without revealing the MPI                       |

### Why it matters

A malicious actor scanning QR codes in bulk at a clinic could:

* **With a classic QR code** : could collect health identities, link names to sensitive programs
* **With the Oomus opaque token** : only collects strings with no usable value

***

## Invoice signatures

Each invoice issued by the platform carries a **cryptographic signature** (keyed hash) ensuring its integrity.

### Properties

| Property        | Guarantee                                                        |
| --------------- | ---------------------------------------------------------------- |
| **Integrity**   | Any altered invoice is immediately detectable                    |
| **Unforgeable** | Impossible to create or modify an invoice without the server key |
| **Verifiable**  | Each invoice can be verified at any time via the API             |

The endpoint `GET /billing/invoices/{id}/verify` allows the authenticity of an invoice to be verified.

***

## Production recommendations

| Measure              | Description                                   |
| -------------------- | --------------------------------------------- |
| **SSL/TLS**          | Valid TLS certificate on all public URLs      |
| **WAF**              | Web Application Firewall to protect the API   |
| **Key rotation**     | Regular signing key rotation policy           |
| **Network firewall** | Restriction of access to authorized IP ranges |
| **Monitoring**       | Monitoring of abnormal access attempts        |

***

## Next steps

* [Offline verification](/security/offline-verification.md) — Field verification portal
* [Security overview](/security/overview.md)
* [Data protection](/security/data-protection.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/security/cryptographic-guarantees.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.