Astrologue-Website/developer/locksmith/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Locksmith — Astrologue Developer</title>
  <meta name="description" content="Locksmith is developer-friendly cryptography for Vala: sodium boxes, X.509, SSH, OpenPGP and WebPush over libsodium, GnuTLS, GPGME and libssh — it implements no cryptography itself. Free software, LGPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="Locksmith — Astrologue Developer">
  <meta property="og:description" content="Developer-friendly cryptography in objects, not byte arrays: sodium boxes, X.509, SSH, OpenPGP and WebPush over libsodium, GnuTLS, GPGME and libssh.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">Locksmith</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Security · Keys, seals and signatures</span></p>
        <h1>Locksmith</h1>
        <p class="lede">Developer-friendly cryptography for Vala, in objects rather than byte arrays. It wraps the battle-tested libraries you already have — libsodium, GnuTLS, GPGME and libssh — and implements no cryptography itself.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>0.1.0</code></dd></div>
          <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;locksmith</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>Why it exists</h2>
          </header>
          <p>Locksmith is an all-purpose cryptography library for Vala. It wraps the crypto libraries a machine already carries — libsodium, GnuTLS, GPGME and libssh — behind simple, object-oriented APIs, so an application gets secure cryptography without touching a byte array unless it wants to.</p>
          <p>The pledge is the design: <strong>Locksmith implements no cryptography itself.</strong> Every primitive comes from those four libraries; Locksmith contributes the object model, the wire formats and the defaults. Nothing new can be wrong in a way its underlying libraries are not, and an audit of the cryptography is an audit of software that has already been audited.</p>
          <p>Its wire formats are the ones the rest of the Astrologue stack already uses: Ed25519 attached signatures are <code>signature||message</code> (USM's format), seals use the X25519 ephemeral-header form, and keys are their raw bytes — so <a href="../usm/">USM</a> and <a href="../statum/">Statum</a> signed slots can move onto Locksmith without changing a byte on disk. A compatibility test suite proves both directions by compiling the original hand-rolled bindings alongside this library.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>What it hands you</h2>
          </header>
          <ul class="docs-features">
            <li><strong>Signing.</strong> Ed25519 keypairs and public keys; attached (<code>signature||message</code>, the USM wire format) and detached signatures.</li>
            <li><strong>Sealing.</strong> X25519 anonymous seals and authenticated two-party boxes.</li>
            <li><strong>Symmetric.</strong> Secretbox keys and ciphers; the nonce travels inside the ciphertext, so it cannot be forgotten.</li>
            <li><strong>Hashing.</strong> One-call and streaming digests (SHA-1/2/3, SHAKE, MD5, BLAKE2b), HMAC, keyed BLAKE2b, PBKDF2, and argon2id password hashing — the only API pointed at passwords.</li>
            <li><strong>Certificates.</strong> X.509 via GnuTLS: RSA/ECDSA/Ed25519 keypairs, DistinguishedNames, certificates, PKCS#10 requests, and Authority objects that issue and verify.</li>
            <li><strong>Ssh.</strong> OpenSSH keys via libssh: generate, load <code>id_ed25519</code> files and <code>authorized_keys</code> lines, fingerprints, passphrase-protected saves, and SSHSIG sign/verify that interops with <code>ssh-keygen&nbsp;-Y</code>.</li>
            <li><strong>Pgp.</strong> OpenPGP via GPGME: hermetic keyrings, key generation, sign/verify, encrypt/decrypt, import/export, armored output.</li>
            <li><strong>WebPush.</strong> RFC 8291 message encryption and RFC 8292 VAPID headers via GnuTLS: browser subscription JSON in, POST-ready body and headers out.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the library</h2>
          </header>
          <p>With USM on your machine, one command acquires, builds and installs the library with its header, Vala binding and introspection:</p>
          <figure class="code-plate">
            <pre><code>usm install locksmith</code></pre>
            <figcaption>USM resolves <code>invercargill-1</code> and <code>invercargill-json</code> itself.</figcaption>
          </figure>
          <p>Building by hand needs the four crypto libraries plus the stack's foundation — on Fedora:</p>
          <figure class="code-plate">
            <pre><code>sudo dnf install meson ninja-build vala libsodium-devel gnutls-devel \
    gpgme-devel libssh-devel libgpg-error-devel json-glib-devel \
    invercargill-devel

git clone &lt;the Locksmith repository&gt;
cd Locksmith
meson setup build &amp;&amp; ninja -C build &amp;&amp; meson test -C build</code></pre>
            <figcaption>The Fedora line and the build commands are the README's own.</figcaption>
          </figure>
          <p>Then compile against it with Vala's usual package mechanism:</p>
          <figure class="code-plate">
            <pre><code>valac --pkg locksmith-1 my-program.vala</code></pre>
            <figcaption>The package ships its five internal bindings alongside, so <code>--pkg locksmith-1</code> resolves everything.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>Quick start, from the README</h2>
          </header>
          <p>Signing, the way USM signs a package listing — but with objects:</p>
          <figure class="code-plate">
            <pre><code>var pair = new Locksmith.Signing.KeyPair.generate();
var signed = pair.sign(new ByteBuffer.from_byte_array(listing.data));
var recovered = pair.public_key.verify(signed);   // null when invalid</code></pre>
            <figcaption>Verbatim from the README's Quickstart. Verification returns null rather than throwing — invalid input is a normal outcome.</figcaption>
          </figure>
          <p>Sealing (anonymous: only the recipient can open) and symmetric encryption (the nonce travels inside):</p>
          <figure class="code-plate">
            <pre><code>var recipient = new Locksmith.Sealing.KeyPair.generate();
var sealed = recipient.public_key.seal(message);
var opened = recipient.unseal(sealed);

var key = new Locksmith.Symmetric.Key.generate();
var cipher = new Locksmith.Symmetric.Cipher();
var stored = cipher.encrypt(key, secret);
var back = cipher.decrypt(key, stored);   // throws CIPHER when tampered</code></pre>
            <figcaption>From the README. Tamper detection is proven by the test suite, not just round-trips.</figcaption>
          </figure>
          <p>A password is never hashed with a digest — it goes to argon2id, and verification is a method on the same object:</p>
          <figure class="code-plate">
            <pre><code>var phc = new Locksmith.Hashing.PasswordHash().hash(password);
// verify later: hasher.verify(phc, attempt)</code></pre>
            <figcaption>Digested data is labelled integrity-only, never password-safe.</figcaption>
          </figure>
          <h3>Certificates and SSH keys</h3>
          <p>An Authority issues and verifies leaves; an SSH key saves and signs in OpenSSH's own formats:</p>
          <figure class="code-plate">
            <pre><code>var root = Locksmith.Certificates.Authority.generate(
    Locksmith.Certificates.KeyType.ED25519, subject, 3650);
var leaf = root.issue_for_public_key(leaf_subject, server.public_key,
    365, sans);
string reason;
leaf.verify(root.certificate, out reason);

var key = new Locksmith.Ssh.Key.generate(Locksmith.Ssh.KeyType.ED25519,
    "me@host");
print("%s\n", key.public_string);   // authorized_keys line
var signature = key.sign(file_contents);   // SSHSIG</code></pre>
            <figcaption>From the README's Quickstart — the SSHSIG output verifies with <code>ssh-keygen -Y</code>.</figcaption>
          </figure>
          <h3>OpenPGP and WebPush</h3>
          <figure class="code-plate">
            <pre><code>var ctx = new Locksmith.Pgp.Context.create();
ctx.home_directory = keyring_dir;
var key = ctx.generate_key("Alice &lt;alice@example.org&gt;");
var signed = ctx.sign(document);

var subscription = new Locksmith.WebPush.Subscription.from_json(json);
var vapid = new Locksmith.WebPush.ApplicationServerKeys.generate();
var message = Locksmith.WebPush.encrypt(subscription, payload);
var headers = Locksmith.WebPush.Vapid.headers(vapid,
    "https://push.example.net", "mailto:admin@example.org");</code></pre>
            <figcaption>A hermetic GPGME keyring for the first; the application-server half of RFC 8291 + 8292 for the second — POST-ready output.</figcaption>
          </figure>
          <h3>The API philosophy</h3>
          <p>Every key, nonce, signature, digest and ciphertext is an <code>Invercargill.BinaryData</code> (concretely <code>ByteBuffer</code>), so <code>to_base64()</code>, <code>to_hex()</code> and equality come free. What a constructor accepts, a method gives back: <code>from_base64</code>/<code>from_hex</code>/<code>from_bytes</code> against <code>to_base64</code>/<code>to_hex</code>/<code>to_der</code>/<code>to_pem</code>. Malformed input throws a <code>Locksmith.Error</code> code; verification — where invalid input is a normal outcome — returns <code>bool</code> or <code>null</code>, so control flow reads like intent.</p>
          <p>Runnable versions of every snippet above live in <code>examples/</code> — one standalone program per subsystem (<code>signing_example.vala</code>, <code>sealing_example.vala</code>, <code>symmetric_example.vala</code>, <code>hashing_example.vala</code>, <code>certificates_example.vala</code>, <code>ssh_example.vala</code>, <code>pgp_example.vala</code>, <code>webpush_example.vala</code>), each smoke-tested by <code>meson test</code>. The library suite itself runs round-trips, tamper detection and RFC vectors through both <code>meson test</code> and USM's <code>test</code> exec, so what is documented here is what is exercised.</p>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>0.1.0</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program. The <code>vapi/</code> libsodium binding is derived from Billy Barrow's ISC-licensed binding, credited in-file.</dd></div>
            <div><dt>Package</dt><dd><code>usm install locksmith</code></dd></div>
            <div><dt>Provides</dt><dd><code>liblocksmith-1.so</code>, <code>locksmith.h</code>, <code>locksmith-1.vapi</code> + <code>.deps</code> plus the five internal bindings (<code>libsodium</code>, <code>gnutls-supplement</code>, <code>gnutls-x509</code>, <code>gpgme</code>, <code>libssh</code>) in <code>share/vala/vapi</code>, <code>locksmith-1.gir</code>, <code>locksmith-1.typelib</code>, <code>locksmith-1.pc</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib, GObject, GIO, <code>libinvercargill-1.so</code>, <code>libinvercargill-json.so</code>, <code>libsodium.so&nbsp;&gt;=26</code>, <code>libgnutls.so&nbsp;&gt;=30</code>, <code>libgpgme.so&nbsp;&gt;=45</code>, <code>libssh.so&nbsp;&gt;=4</code> and the <code>gpg</code> binary.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>clanker/Locksmith</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Related in the catalogue">
            <p>Its neighbours:</p>
            <ul>
              <li><a href="../statum/">Statum</a></li>
              <li><a href="../spry/">Spry</a></li>
              <li><a href="../usm/">USM</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <a class="docs-pager__link docs-pager__link--prev" href="../spry/">
              <span>Previous</span>
              <strong>Spry</strong>
            </a>
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../vallama/">
              <span>Next in the catalogue</span>
              <strong>Vallama</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>