Dev.to Security 🔐 Cybersecurity 👁 0 📖 5 min read

Building Zero-Knowledge Secret Links – AES-256-GCM in the Browser, the URL Fragment and Signed Webhooks

Sharing a database password over Slack is one of those habits every team knows is wrong and keeps doing anyway, because the alternatives feel heavier than the problem. Kriptano is a one-time secret service built around o

Building Zero-Knowledge Secret Links – AES-256-GCM in the Browser, the URL Fragment and Signed Webhooks

Building Zero-Knowledge Secret Links – AES-256-GCM in the Browser, the URL Fragment and Signed Webhooks

Sharing a database password over Slack is one of those habits every team knows is wrong and keeps doing anyway, because the alternatives feel heavier than the problem. Kriptano is a one-time secret service built around one rule – the server should never be able to read what it stores. This post walks through how that works in the browser, how links survive Slack previews, and how the REST API and webhooks fit into scripts and help desks.

The key never reaches the server

When you create a secret, the browser generates a random 256-bit key with crypto.getRandomValues, encrypts the content with AES-256-GCM through the Web Crypto API with a fresh 96-bit IV, and uploads only the ciphertext. The key is appended to the link after the fragment marker. Browsers do not send the fragment in HTTP requests, so the server only ever sees an ID and an encrypted blob.

How a zero-knowledge one-time secret link is encrypted, opened and deleted

A simplified browser-side sketch of the documented scheme:

const b64url = (bytes) =>
  btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");

const key = crypto.getRandomValues(new Uint8Array(32)); // 256-bit key
const iv = crypto.getRandomValues(new Uint8Array(12));  // 96-bit IV

const aesKey = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
const encrypted = await crypto.subtle.encrypt(
  { name: "AES-GCM", iv },
  aesKey,
  new TextEncoder().encode(secretText)
);

// documented format: "v1." + base64url(IV) + "." + base64url(ciphertext + tag)
const payload = "v1." + b64url(iv) + "." + b64url(new Uint8Array(encrypted));

// only the payload is uploaded; the key travels in the link fragment
const fragment = b64url(key);

This illustrates the format, it is not Kriptano's source code. The complete Node.js example is in the API documentation.

Opening a secret without the server knowing the key

The server still has to decide whether a request to open a secret is legitimate. The client derives an authorization token from the key with SHA-256, and the server stores only a hash of that token. Without the fragment there is no token, so the server does not release the ciphertext.

That solves a very practical problem. Slack, Teams and Outlook fetch links to build previews, and a naive one-time link gets "read" by the preview bot before a human ever clicks it. Preview bots do not have the key, so they cannot use up the view.

Passphrase, atomic views and deletion

  • An optional extra passphrase is used only in the browser, to derive the key with PBKDF2-SHA256 and 600,000 iterations, with the key from the link as the salt.
  • Five wrong passphrases destroy the secret.
  • The view counter is updated atomically, so two simultaneous requests cannot both succeed on a one-view link.
  • After the last allowed view the ciphertext is deleted, and expired secrets are removed automatically.

Where this sits next to TLS and encryption at rest

TLS protects data on the wire and encryption at rest protects disks, but in both cases the provider holds the keys. End-to-end encryption keeps the provider blind, and one-view delivery adds a second property – nothing is left behind once the secret has been read.

End-to-end encryption compared with TLS, encryption at rest and one-time encrypted links

Files and secret requests follow the same principle

Large attachments are encrypted in 16–64 MB chunks, with a separate 256-bit key per file and the chunk index in the nonce, and uploaded as encrypted chunks. Secret requests, where someone else sends a credential to you, combine RSA-OAEP 2048 with AES-256-GCM, and the private key stays in your browser.

End-to-end encryption – public and private keys, the server only relays ciphertext

Password generator endpoint without a key

The password generator is also available as an endpoint that needs no API key and is rate-limited per IP to 30 requests per minute and 1,000 per day. It returns passwords, passphrases, PINs or pronounceable passwords:

curl "https://kriptano.com/api/v1/password?type=passphrase&words=5&separator=-&format=text"

With the default JSON format the response also includes entropy_bits and strength, which is handy when a script needs to record how strong a generated value is without logging the value. A generator is only as good as its randomness source and the way it maps random bytes to characters.

How a random password generator works – CSPRNG, rejection sampling, shuffle, local display

Creating secrets from scripts

On the Pro and Pro Plus plans the REST API at https://kriptano.com/api/v1/ accepts a Bearer key created under My account → API:

curl -X POST https://kriptano.com/api/v1/secrets \
  -H "Authorization: Bearer $KRIPTANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret": "STAGING_DB_PASSWORD=<VALUE>", "expires": 86400, "views": 1, "notify": true, "label": "staging db"}'

expires is in seconds (3,600 up to 31,536,000, capped by the plan), views defaults to 1 and label is visible only to you. A plain-text secret reaches the API over HTTPS. If the server should never see the plaintext, encrypt on your side and send ciphertext and auth instead.

Method Path Purpose
GET /api/v1/me account check
POST /api/v1/secrets create a secret
GET /api/v1/secrets list secrets
GET /api/v1/secrets/:id secret metadata
DELETE /api/v1/secrets/:id delete a secret
POST /api/v1/requests create a secret request
GET /api/v1/requests/:id/responses fetch encrypted responses
GET /api/v1/log audit log

Pro allows 60 requests per minute with a key and Pro Plus 300. Going over the limit or the monthly quota returns HTTP 429.

Webhooks and signature verification

Events include secret.created, secret.viewed, secret.locked, secret.deleted, secret.expired, request.created and request.answered. Payloads never contain secret content, keys or links, so a help desk can close a ticket when a temporary password is opened without ever touching the password.

How webhooks flow from the secret sharing API to the recipient and back to the help desk

Each delivery carries Kriptano-Event, Kriptano-Delivery and Kriptano-Signature in the form t=<TIMESTAMP>,v1=<SIGNATURE>. The signature is HMAC-SHA256 over t.body with your whsec_ secret, and t must be within five minutes. A minimal Node.js check:

import crypto from "node:crypto";

export function verifyKriptanoWebhook(rawBody, signatureHeader, webhookSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((pair) => pair.split("="))
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(parts.t + "." + rawBody)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Compare the encoding with the API docs before using it in production. Use the raw request body, not re-serialized JSON, answer with a 2xx status within ten seconds and deduplicate on Kriptano-Delivery. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h, and a 410 response stops them.

Webhook HMAC signature verification in 4 steps

Links on your own domain

Pro Plus can serve secret links from your own subdomain with a TXT and a CNAME record, and send recipient emails from your domain or through your own SMTP server.

Custom domain and custom SMTP – CNAME, TXT, SPF, DKIM and MX records

Try it

The free plan needs no setup and the recipient needs no account. The full architecture is on the Kriptano security page, the endpoints and examples in the API docs, and you can create your first one-time link at kriptano.com.

Povezane analize:

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.