STIR/SHAKEN Toolkit

Reusable Python tooling for STIR/SHAKEN certificate work:

• Local utilities for CSRs, fingerprints, certificate inspection/validation, and STI-PA SPC tokens.
• A PeeringHub ACME workflow for issuing STIR/SHAKEN certificates.
• Python modules that can be reused by higher-level automation.

The package is split into three layers:

• acme_core: provider-neutral RFC 8555 ACME primitives.
• stir_shaken_acme: STIR/SHAKEN-specific TNAuthList, STI-PA, CSR, fingerprint, issuance, and inspection/validation helpers.
• stir_shaken_toolkit.providers.peeringhub: PeeringHub profile defaults and issuance convenience APIs.

Install

pip install stir-shaken-toolkit

Quick Start

Most operators using PeeringHub need four groups of values:

• STI-PA credentials: STIPA_USER_ID, STIPA_PASSWORD, and STIPA_SP_ID.
• The service provider code: STIPA_SPC.
• The PeeringHub ACME key identifier, when PeeringHub provides one: ACME_KID.
• X.509 subject details such as organization, state, locality, and country.

Values can be supplied as CLI arguments, YAML config, or environment variables. For repeated use, a config file or environment variables are usually less noisy than long command lines.

export STIPA_USER_ID=sti-pa-user
export STIPA_PASSWORD=sti-pa-password
export STIPA_SP_ID=818H
export STIPA_SPC=818H
export ACME_KID=peeringhub-kid
export SHAKEN_SUBJECT_ORGANIZATION="Example Telecom"
export SHAKEN_SUBJECT_STATE=TX
export SHAKEN_SUBJECT_LOCALITY=Irving

Prepare or verify the PeeringHub ACME account:

stir-shaken-toolkit peeringhub-account-setup

Issue a certificate:

stir-shaken-toolkit peeringhub-issue

By default, issuance writes artifacts to a new timestamped directory such as ./shaken-cert-20260508T162900Z.

peeringhub-account-setup and peeringhub-issue contact PeeringHub ACME. peeringhub-issue also contacts STI-PA.

Common Commands

PeeringHub issuance:

stir-shaken-toolkit peeringhub-account-setup
stir-shaken-toolkit peeringhub-issue

Local CSR and fingerprint utilities:

stir-shaken-toolkit csr --spc 818H
stir-shaken-toolkit inspect --csr shaken.csr
stir-shaken-toolkit inspect --certificate leaf.pem --json
stir-shaken-toolkit fingerprint --csr shaken.csr
stir-shaken-toolkit validate-key-pair --key account.key --certificate leaf.pem
stir-shaken-toolkit validate-key-pair --key shaken.key --csr shaken.csr

Standalone STI-PA SPC token request:

stir-shaken-toolkit spc-token \
  --spc 818H \
  --fingerprint "SHA256 AA:BB:..."

List STI-PA STI-CA companies:

stir-shaken-toolkit ca-list
stir-shaken-toolkit ca-list --json --details

Run stir-shaken-toolkit --help or stir-shaken-toolkit <command> --help for the current command-line reference.

Configuration Basics

CLI values resolve in this order:

1. Explicit command-line arguments.
2. --config YAML values.
3. Prefixed environment variables.
4. Built-in defaults.

Environment variables use domain prefixes: STIPA_*, ACME_*, SHAKEN_*, and PEERINGHUB_*.

--config is a global option, so place it before the subcommand:

stir-shaken-toolkit --config toolkit.yaml peeringhub-issue

See Configuration for the complete config and environment variable reference.

Important Files

PeeringHub ACME commands use a local account directory. If you do not configure one, the toolkit chooses a per-user platform default.

The durable credential is account.key. Protect it like any other private key. PeeringHub issuance uses this key for ACME account authentication, the STI-PA SPC token fingerprint, the CSR public key, and the final certificate/private-key pair.

The account.json file is a recoverable cache of the PeeringHub ACME account URL. If it is removed, the toolkit can recreate it by signing with the existing account.key.

PeeringHub issuance writes certificate artifacts but does not write a private key into the issuance output directory. The issued certificate belongs with the ACME account key.

For installation and publication details, see Artifacts and Installation.

More Documentation

• Configuration: config keys, environment variables, defaults, and examples.
• PeeringHub Issuance: account setup, issuance behavior, and common failure diagnostics.
• Artifacts and Installation: output files and which certificate file to publish for STIR/SHAKEN use.
• Python API: using the reusable modules directly.
• Shell Completion: generated completion through argcomplete.