> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/troubleshooting/signature-verification.md).

# Signature verification

Fix VerificationError — runtime manifest or artifact hash mismatches and license claim failures (iss / aud / exp / ver) — including trusted key overrides.

Telys is fail-closed: a verified install runs **native-only** and refuses a runtime it can't trust. Verification has two independent parts — the **release signature** over the runtime (manifest + artifact hashes) and the **offline license** (a signed JWT with claims). `telys runtime verify` runs both. A failure surfaces as a `VerificationError` or a license claim error; this page maps each to its cause and fix.

{% hint style="warning" %}
Don't work around a verification failure by disabling checks. A mismatch means the on-disk runtime doesn't match what was signed, or the license doesn't authorize this product. Re-install or re-license instead of overriding trust.
{% endhint %}

## Quick check

```bash
telys runtime verify    # runs signature + license verification, prints what failed
```

The `telys.verify` API checks pieces yourself: `verify_manifest`, `verify_artifact`, and `verify_license`. It requires the `cryptography` package (a hard dependency of the SDK).

## Errors and fixes

<details>

<summary><code>VerificationError</code> — manifest signature invalid</summary>

The signed manifest describes the runtime; its signature is checked with the embedded release public key (RS256, PKCS1v15 + SHA-256).

**Cause:** `telys_manifest.json` or its `telys_manifest.sig` is corrupt, truncated, or was produced with a different signing key.

**Fix:** re-install so the manifest and signature are fetched fresh together, then verify.

```bash
telys runtime install       # or: telys runtime install --file ./bundle --license ./license.jwt
telys runtime verify
```

If you deliberately run a runtime signed by your own release key, point Telys at that key — see "Trusted key overrides" below.

</details>

<details>

<summary><code>VerificationError</code> — artifact hash mismatch</summary>

Each artifact (for example `libty_runtime`, `libame_kernel`) is verified against the SHA-256 recorded in the signed manifest, using a constant-time comparison.

**Cause:** an artifact on disk was modified, partially downloaded, or replaced — its hash no longer matches the manifest.

**Fix:** re-install to restore the exact signed artifacts. Never patch a binary in place.

```bash
telys runtime install
telys runtime verify        # expect a clean pass
```

</details>

<details>

<summary>License rejected — <code>iss</code> / <code>aud</code> / <code>exp</code> / <code>ver</code></summary>

The offline license check is strict: it pins `alg` to RS256, rejects unknown critical headers, and validates the issuer, audience, version, and expiry (with a small grace window), then reads the `products.telys` tier and features.

**Cause and fix**, by claim:

* **`iss` (issuer)** — the issuer isn't the expected one. Default: `https://license.algenta.ai`. For a custom issuer, set `$TELYS_LICENSE_ISSUER`.
* **`aud` (audience)** — the audience isn't accepted. Default: `telys-runtime,algenta-runtime`; override with `$TELYS_LICENSE_AUDIENCE` (comma-separated).
* **`ver` (version)** — only license version `2` is supported. Any other is rejected; obtain a current license via `telys login`.
* **`exp` (expiry)** — the token aged past its expiry plus grace. Sign in again to re-issue, and check your system clock.

```bash
telys login             # refreshes the license to a current, ver:2 token
telys runtime verify
```

</details>

<details>

<summary>Trusted key overrides (custom release or license keys)</summary>

The wheel ships embedded PEM keys: `telys/_keys/telys_release_pub.pem` (runtime signature) and `telys/_keys/telys_license_pub.pem` (license). Override them for an enterprise or self-signed pipeline.

**Cause:** you sign runtimes or licenses with your own keys and need Telys to trust them.

**Fix:** point Telys at your public keys and expected claims via environment variables.

```bash
# Release-signature key (verifies the runtime manifest):
export TELYS_RELEASE_PUBKEY_FILE=/opt/telys/keys/release_pub.pem
# or inline PEM: export TELYS_RELEASE_PUBKEY="-----BEGIN PUBLIC KEY----- ..."

# License key + expected claims:
export TELYS_LICENSE_PUBKEY_FILE=/opt/telys/keys/license_pub.pem
export TELYS_LICENSE_ISSUER=https://license.example.com
export TELYS_LICENSE_AUDIENCE=telys-runtime,algenta-runtime

telys runtime verify
```

You can also verify programmatically with pinned keys:

```python
from telys.verify import verify_license
from datetime import datetime, timezone

claims = verify_license(
    token,                       # the JWT string
    now=int(datetime.now(timezone.utc).timestamp()),  # verify_license wants a Unix int
    product="telys",
)
print(claims["products"]["telys"])   # tier + features
```

Override keys only when you control the signing pipeline; otherwise leave the embedded keys in place.

</details>

## Next steps

If verification points at the license itself rather than the runtime signature, fix it at the sign-in / plan layer.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>License &#x26; login issues</strong></td><td>Refresh an expired license, switch plans, sign in headless.</td><td><a href="https://docs.telys.ai/troubleshooting/license-and-login.md">License &amp; login</a></td></tr><tr><td><strong>Verify the runtime signature</strong></td><td>The trust model and the full verification walkthrough.</td><td><a href="https://docs.telys.ai/security/runtime-signature-verification.md">Verify the runtime</a></td></tr></tbody></table>

Next: [License & login issues](https://docs.telys.ai/troubleshooting/license-and-login.md)
