flexaccess-keys

Shared Ed25519 authentication key format and Rust tooling for FlexAccess applications.

This repository is the canonical home for:

• the app-independent ed25519-sec: private-key and ed25519-pub: public-key tokens;
• generated private-key files and SSH-like authorized-key entries;
• key generation, parsing, derivation, raw signing, and strict verification;
• common generate-auth-key and show-auth-key command behavior.

Application authentication protocols are intentionally out of scope. A consumer must define its own domain-separated signed message and wire protocol; the library only signs or verifies the bytes supplied by that consumer.

Key format

docs/key-format.md is the normative specification; consumers must not reimplement the format. In short, both tokens hold exactly 32 raw bytes as unpadded URL-safe base64:

ed25519-sec:<private seed>
ed25519-pub:<public key>

A generated private-key file is self-describing while remaining parseable as a single secret token:

# Ed25519 authentication key
# Created: 2026-08-17T19:00:00Z
# Public key: ed25519-pub:<public key> alice laptop
ed25519-sec:<private seed>

An authorized-keys document contains one public token per line, optionally followed by a comment. Blank lines and # comments are ignored:

ed25519-pub:<public key> alice laptop
ed25519-pub:<public key> build server

Private key files created with --output use mode 0600 on Unix.

Installation

You only need the binary in your PATH; no runtime dependencies or package managers are required.

Linux & macOS:

curl -sSL https://flexaccessdev.github.io/flexaccess-keys/install.sh | bash

Windows:

irm https://flexaccessdev.github.io/flexaccess-keys/install.ps1 | iex

This installs flexaccess-keys.

Advanced installation options

Install a specific release:

# Linux/macOS
curl -sSL https://flexaccessdev.github.io/flexaccess-keys/install.sh | bash -s v0.0.2

# Windows
& ([scriptblock]::Create((irm https://flexaccessdev.github.io/flexaccess-keys/install.ps1))) v0.0.2

By default the installer pulls the latest stable release. Use --prerelease on Linux/macOS or -PreRelease on Windows to install the newest prerelease.

Note: Prerelease artifacts may not include Windows binaries. If one is unavailable, use a stable release or build from source.

From source

Install directly from GitHub:

cargo install --git https://github.com/flexaccessdev/flexaccess-keys --features cli \
  flexaccess-keys

Or run from a local checkout without installing:

cargo run --release --features cli -- generate-auth-key "alice laptop" > client.key
cargo run --release --features cli -- show-auth-key --private-key-file client.key

CLI

Generate a private key and derive its authorized-key entry:

flexaccess-keys generate-auth-key "alice laptop" > client.key
flexaccess-keys show-auth-key --private-key-file client.key > authorized_keys

# 0.5-compatible structured generation for automation
flexaccess-keys generate-auth-key "alice laptop" --json
# {"authorized_key":"ed25519-pub:... alice laptop","private_key":"ed25519-sec:..."}

Like age-keygen, generate-auth-key writes a self-describing private-key file to stdout by default; its # Public key: header includes the authorized-key entry and comment. Use --output client.key to create the private-key file with mode 0600 on Unix instead. Successful generation writes nothing to stderr. The explicit --json mode retains the 0.5 command behavior: it writes both the authorized-key entry and private-key token to stdout as one JSON object without creating a file.

Public-key output is deliberately separate. show-auth-key derives the entry from the private key and writes it to stdout; add --json and select .authorized_key with jq for structured automation. Stderr is reserved for errors in every mode.

If the binary is unavailable, the same tokens can be produced with OpenSSL or Python; see docs/fallback-key-generation.md.

Library

Before the first tagged release, consumers can use the Git repository directly:

[dependencies]
flexaccess-keys = { git = "https://github.com/flexaccessdev/flexaccess-keys", default-features = false }

Add a rev for reproducible builds.

Features

The default feature set is empty so library consumers compile only the key format, Ed25519 operations, secure randomness, and file handling they use.

• commands adds shared command output helpers and JSON serialization.
• cli adds the standalone binary and implies commands.
• fast enables ed25519-dalek's larger precomputed verification tables.

Applications embedding the shared command helpers can opt in without pulling in Clap:

flexaccess-keys = { git = "https://github.com/flexaccessdev/flexaccess-keys", features = ["commands"] }

The primary API consists of:

• PrivateKey: generate, parse, serialize, derive a public key, and sign an application-defined message;
• PublicKey: parse, serialize, and strictly verify a signature;
• AuthorizedKey and AuthorizedKeys: comments and authorized-key parsing;
• private-key and authorized-key file loaders;
• shared implementations of the two CLI operations.

The optional cli feature enables the standalone binary and its Clap parser; the default library feature set remains empty.

Consumers

• tunnel-rs uses this crate for client authentication key management while retaining its own challenge transcript.
• flextunnel is the planned phase-2 consumer.