# dkg/monkeysphere architecture

> Architecture diagram of the GitHub repository dkg/monkeysphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dkg/monkeysphere
- Repository: https://github.com/dkg/monkeysphere

## Overview

##### Project type and purpose
- Monkeysphere is an open-source security tool / framework (not a web app) that extends the OpenPGP “web of trust” to SSH. It provides a suite of CLI utilities, scripts, and configuration files to manage SSH known_hosts and authorized_keys via GnuPG keys.

##### File structure
- Top-level directories:
- etc – default configuration files (monkeysphere.conf, host/authentication configs, cron job)
- src – the C binaries and shell/PERL scripts that implement Monkeysphere commands
- src/share – library of helper scripts (m, ma, mh subcommands) called by the main binaries
- tests – automated test fixtures for configs, keyrings, SSH setups
- utils – packaging and release-prep scripts
- man – manpages for each command
- examples – sample configuration and usage snippets
- Build & deploy: Makefile, packaging/ (macports, slackware)
- Transitions: contains upgrade scripts for database/migration logic.

##### Key insights from README
- Core flow: CLI commands invoke GnuPG (via Crypt::OpenSSL::RSA or gpg2), verify keys, then update SSH files.
- Dependencies: GnuPG ≥2.1.11, Perl, Bash, OpenSSH ssh-keygen, lockfile tools.
- Intended use cases: ad-hoc CLI, cron-driven periodic updates.

a. Main components:
- User/Admin – invokes Monkeysphere commands or cron
- Monkeysphere CLI Layer – C programs (agent-transfer, monkeysphere, openpgp2ssh, pem2openpgp, host/authentication subcommands)
- Script Library – share/m*, share/ma*, share/mh* helper scripts
- Configuration – etc/*.conf, ~/.monkeysphere/
- GnuPG Service – GPG keyrings, gpg2 daemon or process
- OpenSSH Tools – ssh-keygen, known_hosts, authorized_keys
- File System – clients’ ~/.ssh and /etc/ssh files
- Cron Daemon – runs scheduled updates in etc/cron.hourly
- Test Harness – automated tests invoking the above in a sandbox

b. Relationships & interactions:
1. Admin/User or cron invokes a Monkeysphere CLI binary
2. CLI binary loads configuration from etc/ or ~/.monkeysphere
3. It calls out to GnuPG (gpg2) or Crypt::OpenSSL::RSA to fetch/verify OpenPGP keys
4. It invokes share scripts (m, ma, mh) to perform key lookups, trust calculations, and file transformations
5. It calls ssh-keygen or directly writes to known_hosts/authorized_keys
6. Lockfile is used to serialize concurrent writes
7. SSH connections subsequently use the managed key files

c. Architectural patterns & principles:
- Modular CLI: each binary does one job (Unix philosophy)
- Shared script library: DRY helper functions in src/share
- Layered external integration: clearly separated GPG layer and SSH layer
- Migration/versioning: transitions directory holds upgrade scripts

d. Technologies & frameworks:
- C for high-performance CLI clients
- Bash / Perl scripts for logic in src/share/*
- GnuPG (gpg2), Crypt::OpenSSL::RSA
- OpenSSH’s ssh-keygen
- lockfile-progs or procmail lockfile

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Users & Scheduler
    subgraph "Users & Scheduler"
        direction TB
        User["User/Admin"]:::external
        Cron["Cron Daemon"]:::external
    end

    %% Layer 2: Monkeysphere CLI Binaries
    subgraph "Monkeysphere CLI Binaries" 
        direction TB
        AT["agent-transfer"]:::internal
        MS["monkeysphere"]:::internal
        MAUTH["monkeysphere-authentication"]:::internal
        MAUTHK["monkeysphere-authentication-keys-for-user"]:::internal
        MH["monkeysphere-host"]:::internal
        O2S["openpgp2ssh"]:::internal
        P2O["pem2openpgp"]:::internal
    end

    %% Layer 3: Script Library & Configuration
    subgraph "Script Library" 
        direction TB
        subgraph "m scripts"
            direction TB
            M1["gen_subkey"]:::internal
            M2["import_subkey"]:::internal
            M3["keys_for_userid"]:::internal
            M4["ssh_proxycommand"]:::internal
            M5["subkey_to_ssh_agent"]:::internal
            M6["update_authorized_keys"]:::internal
            M7["update_known_hosts"]:::internal
        end
        subgraph "ma scripts"
            direction TB
            MA1["add_certifier"]:::internal
            MA2["diagnostics"]:::internal
            MA3["list_certifiers"]:::internal
            MA4["remove_certifier"]:::internal
            MA5["setup"]:::internal
            MA6["update_users"]:::internal
        end
        subgraph "mh scripts"
            direction TB
            MH1["add_name"]:::internal
            MH2["add_revoker"]:::internal
            MH3["diagnostics"]:::internal
            MH4["import_key"]:::internal
            MH5["publish_key"]:::internal
            MH6["revoke_key"]:::internal
            MH7["revoke_name"]:::internal
            MH8["set_expire"]:::internal
        end
        Common["common"]:::internal
        CheckPerms["checkperms"]:::internal
        DefaultEnv["defaultenv"]:::internal
        KeyTrans["keytrans"]:::internal
    end

    subgraph "Configuration" 
        direction TB
        Conf1["etc/monkeysphere.conf"]:::config
        Conf2["etc/monkeysphere-host.conf"]:::config
        Conf3["etc/monkeysphere-authentication.conf"]:::config
        CronJob["etc/cron.hourly/monkeysphere"]:::config
        UserConf["~/.monkeysphere/"]:::config
    end

    %% Layer 4: External Dependencies
    subgraph "External Dependencies"
        direction TB
        GPG["GnuPG (gpg2)"]:::external
        SSHKG["ssh-keygen"]:::external
        Lock["lockfile tools"]:::external
    end

    %% Layer 5: Filesystem
    subgraph "Filesystem"
        direction TB
        KnownHosts["known_hosts"]:::storage
        AuthKeys["authorized_keys"]:::storage
    end

    %% Other Components
    subgraph "Other Components"
        direction TB
        Transitions["transitions"]:::internal
        Tests["tests"]:::internal
        Manpages["manpages"]:::internal
        Packaging["packaging & utils"]:::internal
    end

    %% Connections
    User -->|invokes| AT
    User -->|invokes| MS
    User -->|invokes| MAUTH
    User -->|invokes| MAUTHK
    User -->|invokes| MH
    User -->|invokes| O2S
    User -->|invokes| P2O
    Cron -->|schedules| MS

    AT -->|loads config| Conf1
    MS -->|loads config| Conf1
    MAUTH -->|loads config| Conf3
    MH -->|loads config| Conf2

    AT -->|calls script| M*
    MS -->|calls script| M*
    MAUTH -->|calls script| MA*
    MH -->|calls script| MH*

    subgraph script-calls
        M* --> GPG
        MA* --> GPG
        MH* --> GPG
    end

    AT -->|uses| Lock
    MS -->|uses| Lock
    MAUTH -->|uses| Lock
    MH -->|uses| Lock

    AT -->|invokes| SSHKG
    MS -->|invokes| SSHKG

    M6 -->|writes| AuthKeys
    M7 -->|writes| KnownHosts

    Tests -.->|validates| MS
    Tests -.->|validates| M*
    Packaging -.-> MS
    Transitions -.-> MS

    %% Click Events for CLI Binaries
    click AT "https://github.com/dkg/monkeysphere/blob/master/src/agent-transfer/main.c"
    click MS "https://github.com/dkg/monkeysphere/tree/master/src/monkeysphere"
    click MAUTH "https://github.com/dkg/monkeysphere/tree/master/src/monkeysphere-authentication"
    click MAUTHK "https://github.com/dkg/monkeysphere/tree/master/src/monkeysphere-authentication-keys-for-user"
    click MH "https://github.com/dkg/monkeysphere/tree/master/src/monkeysphere-host"
    click O2S "https://github.com/dkg/monkeysphere/tree/master/src/openpgp2ssh"
    click P2O "https://github.com/dkg/monkeysphere/tree/master/src/pem2openpgp"

    %% Click Events for Script Library
    click M1 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/gen_subkey"
    click M2 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/import_subkey"
    click M3 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/keys_for_userid"
    click M4 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/ssh_proxycommand"
    click M5 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/subkey_to_ssh_agent"
    click M6 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/update_authorized_keys"
    click M7 "https://github.com/dkg/monkeysphere/tree/master/src/share/m/update_known_hosts"
    click MA1 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/add_certifier"
    click MA2 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/diagnostics"
    click MA3 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/list_certifiers"
    click MA4 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/remove_certifier"
    click MA5 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/setup"
    click MA6 "https://github.com/dkg/monkeysphere/tree/master/src/share/ma/update_users"
    click MH1 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/add_name"
    click MH2 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/add_revoker"
    click MH3 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/diagnostics"
    click MH4 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/import_key"
    click MH5 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/publish_key"
    click MH6 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/revoke_key"
    click MH7 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/revoke_name"
    click MH8 "https://github.com/dkg/monkeysphere/tree/master/src/share/mh/set_expire"
    click Common "https://github.com/dkg/monkeysphere/tree/master/src/share/common"
    click CheckPerms "https://github.com/dkg/monkeysphere/tree/master/src/share/checkperms"
    click DefaultEnv "https://github.com/dkg/monkeysphere/tree/master/src/share/defaultenv"
    click KeyTrans "https://github.com/dkg/monkeysphere/tree/master/src/share/keytrans"

    %% Click Events for Config
    click Conf1 "https://github.com/dkg/monkeysphere/blob/master/etc/monkeysphere.conf"
    click Conf2 "https://github.com/dkg/monkeysphere/blob/master/etc/monkeysphere-host.conf"
    click Conf3 "https://github.com/dkg/monkeysphere/blob/master/etc/monkeysphere-authentication.conf"
    click CronJob "https://github.com/dkg/monkeysphere/tree/master/etc/cron.hourly/monkeysphere"
    click UserConf "https://github.com/dkg/monkeysphere/tree/master/~/.monkeysphere/"

    %% Click Events for Other Components
    click Transitions "https://github.com/dkg/monkeysphere/tree/master/src/transitions"
    click Tests "https://github.com/dkg/monkeysphere/tree/master/tests"
    click Manpages "https://github.com/dkg/monkeysphere/tree/master/man"
    click Packaging "https://github.com/dkg/monkeysphere/tree/master/packaging"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#045FB4,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#186A3B,stroke-width:1px
    classDef config fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
    classDef storage fill:#FADBD8,stroke:#922B21,stroke-width:1px
```
