NAME
Langertha::Holmgang::Sim::Linux::Pki - Certificates and keys as data: openssl, update-ca-certificates, verification in the client
VERSION
version 0.001
SYNOPSIS
# from the Linux simulator
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Pki::openssl( $dev, \@argv, $ctx, $stdin );
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Pki::update_ca_certificates( $dev, \@argv, $ctx );
# for case authors: PEM text of a certificate or key
my $pem = Langertha::Holmgang::Sim::Linux::Pki::pem( cert => 'shop-2026' );
DESCRIPTION
Certificates are data in the state; their PEM text in files only refers to them (cai-platform docs/entwurf-evals.md §3.3). The catalog lives under pki of one or more devices (merged):
pki:
now: "2026-10-24T08:00:00Z" # time for validity
certs:
shop-2026: { subject: "CN=shop.example.com", sans: [shop.example.com, www.shop.example.com],
issuer: int-r3, not_before: "2026-09-01T00:00:00Z", not_after: "2026-11-30T00:00:00Z",
key: k-shop-2026, serial: "04A1…" }
int-r3: { subject: "C=US,O=Example Trust,CN=Example R3", issuer: root-x1, ca: true, key: k-int, … }
root-x1: { subject: "C=US,O=Example Trust,CN=Example Root X1", issuer: root-x1, ca: true, … }
keys: { k-shop-2026: { bits: 2048, passphrase: "…" } } # passphrase: only for encrypted files
trusted: [ root-x1 ] # trust store of this device (client)
installed: [ … ] # by the simulator: installed via update-ca-certificates
A PEM block carries base64("cai-sim-cert:<id")> as its body (or key, encrypted in an ENCRYPTED PRIVATE KEY block); files stay text, cat a b > chain works as for real. CSRs carry their content (subject, names, key) canonically in the block. Self-generated certificates and keys (openssl req -x509 -newkey) are added under the device's pki.
openssl: x509 (-in/input, -noout, -subject, -issuer, -dates, -startdate, -enddate, -serial, -fingerprint [-sha256|-sha1], -ext subjectAltName, -text, -checkend N, -modulus, -pubkey, -subject_hash), rsa/pkey (-in, -noout, -modulus, -check, -text, -pubout, -out, -passin pass:…|file:…|env:…), verify [-CAfile] [-untrusted], s_client -connect h:p [-servername] [-showcerts] [-tls1_2|-tls1_3|-tls1_1|-tls1] [-CAfile], crl2pkcs7 -nocrl -certfile, pkcs7 -print_certs, req (-new, -x509, -key, -newkey rsa:N, -nodes/-noenc, -keyout, -out, -subj, -addext, -config with [alt_names], -days, -in … -noout -text|-subject|-verify), dgst -sha256/sha256/md5 over the input, version. Anything else: gap in the simulation.
update-ca-certificates installs the certificates of all *.crt under /usr/local/share/ca-certificates (not other extensions — as on Debian).
"client_verify" checks what a server presents, like curl with OpenSSL: chain up to a trusted certificate (trusted + installed of the client, or only --cacert), validity, name (SAN, otherwise CN).
pem
my $text = pem( cert => 'shop-2026' ); # also key, enckey, pub
PEM text (with a trailing newline) for an entry of the catalog.
blocks
my @b = blocks($text); # ( { kind => cert|key|enckey|csr|pub|p7|bad|other, id, text }, … )
The PEM blocks of a text in order; a body that refers to nothing in the catalog is bad.
catalog
my $cat = catalog($state); # { certs, keys, now }
The catalog from pki of all devices, merged.
dn
dn('C=US,O=Example Trust,CN=Example R3'); # "C = US, O = Example Trust, CN = Example R3"
A subject written the way OpenSSL 3 prints it.
modulus
The (simulated) modulus of a key, the same for certificate and key.
verify_chain
my $err = verify_chain( $catalog, $leaf, \@intermediates, \@trusted );
# undef = valid, otherwise { code, depth, cert }
name_matches
name_matches( $certificate, 'www.shop.example.com' );
Does the name match the SANs (with *. wildcard for exactly one level), or, without SANs, the CN?
trust_of
The certificates a device trusts as a client (list of IDs).
client_verify
my $bad = client_verify( $state, $from, $tls, $req ); # undef or [ 60, "(60) …" ]
tls_lines
Lines of curl -v about the presented certificate.
openssl
my ( $out, $ok ) = openssl( $dev, \@argv, $ctx, $stdin );
The command openssl (subcommands see above).
csr_pem_for
my $text = csr_pem_for( subject => 'CN=shop.example.com', sans => [ 'shop.example.com' ], key => 'k-shop' );
PEM text of a CSR (canonical: subject fields and names sorted) — for rules on a generated CSR file.
update_ca_certificates
The command update-ca-certificates: installs the *.crt under /usr/local/share/ca-certificates into pki.installed and rewrites the bundle /etc/ssl/certs/ca-certificates.crt if it is in the state.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.