# zsrv/supermicro-product-key architecture

> Architecture diagram of the GitHub repository zsrv/supermicro-product-key, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zsrv/supermicro-product-key
- Repository: https://github.com/zsrv/supermicro-product-key

## Overview

##### Project Type and Purpose
- This is a Go-based command-line utility (CLI tool) for encoding, decoding, verifying, and brute-forcing Supermicro BMC product keys in three formats: OOB, Non-JSON, and JSON.
- It consists of a set of subcommands (oob, nonjson, json) each implementing key format–specific logic, backed by shared crypto and network helper libraries.

##### File Structure Analysis
- Top level:
- cmd/        → cobra-style CLI entrypoints and subcommand wiring (root.go, json.go, nonjson.go, oob.go).
- main.go     → invokes the cobra command tree.
- pkg/        → reusable packages:
– pkg/build/version.go        → versioning info injected at build time.
– pkg/crypto/…                → big‐integer arithmetic (assembly + Go) and RSA routines for signatures.
– pkg/net/parse.go, mac.go    → MAC‐address parsing, formatting, and brute-force scanning.
– pkg/json/, pkg/nonjson/, pkg/oob/ → format-specific encode/decode/brute-force implementations.
- Configuration & CI:
- .github/workflows/main.yml    → GitHub Actions for build/test/release.
- .goreleaser.yaml              → goreleaser config for cross-platform binaries.
- Dependencies managed via go.mod/go.sum.

##### README Insights
- Details usage patterns for each subcommand, key formats, SKU lists, and algorithmic steps.
- Describes how each format binds to a MAC address, what fields are encoded, and signature verification for JSON keys.
- Mentions external consumer (the BMC firmware) that verifies/activates keys.

a. Main Components
- User & CLI Interface: Parses args, displays help/usage.
- Command Dispatcher: Routes to oob/nonjson/json handlers.
- Format Handlers: Each implements:
- Input normalization (MAC, JSON payload).
- Encode/Decode logic.
- Brute-force loop if requested.
- Crypto Engine: BigMod math and RSA signature/verification.
- Network Utility: MAC parsing/generation helpers.
- Build/Version Service: Embeds version metadata.
- CI/CD Pipeline: GitHub Actions + goreleaser producing cross-compiled binaries.
b. Relationships & Data Flow
- User invokes CLI → cobra parser → dispatch to Format Handler.
- Format Handler calls Crypto Engine + Network Utility.
- Crypto Engine may call internal bigmod assembly or RSA code.
- Brute-force loops iterate MAC address candidates via Network Utility → feed into encode/verify functions.
- Output formatted back to CLI (text, JSON).
- Code changes trigger CI pipeline → automated tests → release artifacts.
c. Architectural Patterns
- Modular package separation (single-responsibility for each format).
- Command Pattern via cobra for subcommands.
- Layered approach: CLI layer → application (handlers) → infrastructure (crypto, net).
- Use of internal packages for low-level performance code.
d. Key Technologies & Libraries
- Go and go-modules for dependency management.
- Cobra (implied) for CLI command wiring.
- Assembly and pure-Go big integer math in pkg/crypto/internal/bigmod.
- RSA routines in pkg/crypto/rsa.
- goreleaser for artifact publishing.
- GitHub Actions for CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    CLI["CLI Parser & Dispatcher"]:::cli
    subgraph "Format Handlers"
        JSONH["JSON Handler"]:::handler
        NONJSONH["Non-JSON Handler"]:::handler
        OOBH["OOB Handler"]:::handler
    end
    subgraph "Shared Services"
        Crypto["Crypto Engine"]:::shared
        Net["Network Utility"]:::shared
        BuildVer["Build/Version Service"]:::shared
    end
    subgraph "CI/CD Pipeline"
        Dev["Developer"]:::dev
        GH["GitHub Actions"]:::ci
        GR["goreleaser"]:::ci
        Artifacts["Cross-compiled Binaries"]:::ci
    end

    User -->|"invoke CLI"| CLI
    CLI -->|"dispatch to handlers"| JSONH
    CLI -->|"dispatch to handlers"| NONJSONH
    CLI -->|"dispatch to handlers"| OOBH
    CLI -->|"embeds version info"| BuildVer

    JSONH -->|"uses"| Crypto
    JSONH -->|"uses"| Net
    NONJSONH -->|"uses"| Crypto
    NONJSONH -->|"uses"| Net
    OOBH -->|"uses"| Crypto
    OOBH -->|"uses"| Net

    Dev -->|"push code"| GH
    GH -->|"build & test"| GR
    GR -->|"release"| Artifacts

    click CLI "https://github.com/zsrv/supermicro-product-key/blob/main/main.go"
    click CLI "https://github.com/zsrv/supermicro-product-key/blob/main/cmd/root.go"
    click CLI "https://github.com/zsrv/supermicro-product-key/blob/main/cmd/json.go"
    click CLI "https://github.com/zsrv/supermicro-product-key/blob/main/cmd/nonjson.go"
    click CLI "https://github.com/zsrv/supermicro-product-key/blob/main/cmd/oob.go"
    click JSONH "https://github.com/zsrv/supermicro-product-key/blob/main/pkg/json/json.go"
    click NONJSONH "https://github.com/zsrv/supermicro-product-key/blob/main/pkg/nonjson/nonjson.go"
    click OOBH "https://github.com/zsrv/supermicro-product-key/blob/main/pkg/oob/oob.go"
    click Crypto "https://github.com/zsrv/supermicro-product-key/tree/main/pkg/crypto/internal/bigmod/"
    click Net "https://github.com/zsrv/supermicro-product-key/blob/main/pkg/net/parse.go"
    click BuildVer "https://github.com/zsrv/supermicro-product-key/blob/main/pkg/build/version.go"
    click GH "https://github.com/zsrv/supermicro-product-key/blob/main/.github/workflows/main.yml"
    click GR "https://github.com/zsrv/supermicro-product-key/blob/main/.goreleaser.yaml"

    classDef user fill:#a2d2ff,stroke:#000
    classDef dev fill:#ffafcc,stroke:#000
    classDef cli fill:#caffbf,stroke:#000
    classDef handler fill:#ffeb99,stroke:#000
    classDef shared fill:#d0bfff,stroke:#000
    classDef ci fill:#ffc6ff,stroke:#000
```
