protoml-parser
Version:
ProtoML is a lightweight, declarative markup language designed for writing and structuring meeting protocols, notes and task lists in a human-readable and machine-parseable format.
120 lines (108 loc) • 6.21 kB
HTML
<html>
<head>
<meta charset="UTF-8">
<title>Sign - ProtoML 1.4.2+build67</title>
<link rel="stylesheet" href="help.css">
</head>
<body>
<nav class="topnav">
<a href="../toc.html">Contents</a>
<span class="version">ProtoML 1.4.2+build67</span>
</nav>
<main class="page">
<h1>Sign</h1>
<div class="topic-meta">Topic: <code>sign</code></div>
<h2>Explanation</h2>
<p><code>protoparser sign <macro|pml> <file> <private_key.pem> <author> [key_id]</code> creates a detached RSA-SHA256 signature file next to the target.</p>
<p>This works for both:</p>
<ul>
<li>macro files used in rendering workflows</li>
<li>normal <code>.pml</code> files used in governance, approval, release, policy, and record workflows</li>
</ul>
<p>Examples:</p>
<ul>
<li><code>warning.pml</code> becomes <code>warning.pml.sig.json</code></li>
<li><code>Meeting.pml</code> becomes <code>Meeting.pml.sig.json</code></li>
</ul>
<p>The sidecar contains:</p>
<ul>
<li>file hash</li>
<li>author name</li>
<li>optional key ID</li>
<li>public key</li>
<li>signature payload</li>
</ul>
<p>This keeps ProtoML source files clean and avoids adding extra inline signature syntax to the language itself.</p>
<p>Registry-backed workflow:</p>
<p>1. create or reuse an RSA private key 2. export the matching public key in PEM format 3. sign the macro file or the governance <code>.pml</code> file 4. publish the matching public key in the registry <code>authors</code> section 5. run <code>verify</code> or <code>trust</code>, either through the nearest project <code>protoml.macros.json</code> or with explicit <code>-trustRegistry=...</code></p>
<p>Key bootstrap with OpenSSL:</p>
<p>Create a private key at a chosen export path:</p>
<p><code>openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out "./keys/jane-director-private.pem"</code></p>
<p>Export the matching public key at a chosen path:</p>
<p><code>openssl rsa -pubout -in "./keys/jane-director-private.pem" -out "./keys/jane-director-public.pem"</code></p>
<p>Typical governance bootstrap:</p>
<ul>
<li>keep the private key only with the signer, for example <code>./keys/jane-director-private.pem</code></li>
<li>export the public key to a distributable path, for example <code>./keys/jane-director-public.pem</code></li>
<li>copy the public key contents into the registry <code>authors[].keys[].public_key</code> field</li>
<li>keep a stable <code>key_id</code> such as <code>board-chair-2026</code> so users can match signatures to rotated keys later</li>
</ul>
<p>Detached sidecar workflow outside a registry:</p>
<p>Author side:</p>
<ul>
<li>create or reuse an RSA private key</li>
<li>export the matching public key PEM if users should be able to verify the file without a registry</li>
<li>run <code>protoparser sign macro ...</code> or <code>protoparser sign pml ...</code></li>
<li>distribute both the signed file and the generated <code>*.sig.json</code> sidecar together</li>
<li>distribute the public key to users through a documented channel</li>
</ul>
<p>User side:</p>
<ul>
<li>keep the signed file and its matching <code>*.sig.json</code> file together</li>
<li>run <code>protoparser verify macro ...</code> or <code>protoparser verify pml ...</code> to verify the detached signature cryptographically</li>
<li>if no trust registry is available, treat the result as manually verified content rather than registry-trusted content</li>
</ul>
<p>Governance note:</p>
<ul>
<li>signing a normal <code>.pml</code> file is useful for controlled documents such as procedures, approvals, release checklists, policy texts, onboarding records, and reviewable internal records</li>
<li>the detached sidecar proves integrity and authorship of the document file itself; it does not replace <code>@signatures</code> or <code>@approvals</code> blocks inside the ProtoML content</li>
</ul>
<p>If you want built-in macros to participate in the same trust model as external macros, they should also ship with detached <code>*.sig.json</code> files and a matching trusted author entry in a documented trust registry. Built-in bundled macros can also be trusted without a detached sidecar when they match the shipped built-in hash manifest and do not trigger hard risk flags, but that origin-based trust only applies to the known bundled files.</p>
<h2>Examples</h2>
<pre><code>Full signing and verification flow:
protoparser sign macro "./macros/warn_box.pml" "./keys/alice-private.pem" "Alice" alice-main
Registry author entry:
{
"name": "Alice",
"trust": "trusted",
"keys": [
{
"id": "alice-main",
"public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}
]
}
Verification:
protoparser verify macro "./macros/warn_box.pml" -trustRegistry="./my-registry"
protoparser trust "Meeting.pml" -trustRegistry="./my-registry"
Detached sidecar example without a registry:
Author:
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out "./keys/alice-private.pem"
openssl rsa -pubout -in "./keys/alice-private.pem" -out "./keys/alice-public.pem"
protoparser sign macro "./shared/warn_box.pml" "./keys/alice-private.pem" "Alice" alice-main
Distribute together:
- ./shared/warn_box.pml
- ./shared/warn_box.pml.sig.json
- ./keys/alice-public.pem
User:
protoparser verify macro "./shared/warn_box.pml"
Short examples:
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out "./keys/alice-private.pem"
openssl rsa -pubout -in "./keys/alice-private.pem" -out "./keys/alice-public.pem"
protoparser sign macro "./macros/warn_box.pml" "./keys/alice-private.pem" "Alice" alice-main
protoparser sign pml "./meetings/board.pml" "./keys/alice-private.pem" "Alice" alice-main
protoparser verify pml "./meetings/board.pml" -trustRegistry="./authors-registry"</code></pre>
</main>
</body>
</html>