From f9a77c5c27aede4e5978eb55d9b7af781b680a1d Mon Sep 17 00:00:00 2001 From: João Augusto Costa Branco Marado Torres Date: Tue, 24 Jun 2025 12:08:41 -0300 Subject: feat!: initial commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: João Augusto Costa Branco Marado Torres --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..a205558 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# + +# Signing and verifying blog posts (incomplete) + +Posts don't have to be signed. + +Assuming you have the repo cloned. + +1. Write a blog post in [`./src/content/blog/`][blog dir] using the + [`TEMPLATE`][blog template] in that directory by duplicating it and renaming + it to what will be displayed on the URL (I'd like to keep the format of the + slug only ASCII, lowercase letters, numbers and hyphens) plus the `.md` + extension for markdown: + + cp ./src/content/blog/TEMPLATE ./src/content/blog/.md + +2. Write the blog post. Addicionally, you will have to fill the _frontmatter_. + Commented lines in the _frontmatter_ with `#` are optional. But it's a good + idea to fill some of them, namely: + + - `signer.name` - Can be used to find your public key in Keyserver for + example; + - `signer.email` - Can be used to find your public key in Keyserver, or from + a signed e-mail that the user might have recieved; + - `signer.website[]` - Can be used to get your public key from the website's + certificate assuming it uses TLS, or from your GitHub's profile, + , or by reading the DNS records, the website uses WKD + protocol. Basically for signature statements; + - `signer.publickey.armor` - Your public key in ASCII armor format so that + they can import it; + - `signer.publickey.url` - URL to your public key for people to download from + and import it; + - `signer.publickey.keyID` - Your public key ID to find your public key in + Keyserver for example; + - `signer.publickey.fingerprint` - Your public key fingerprint; + - `signer.publickey.keyserver[]` - Key servers where we can find your public + key. + + The _frontmatters_ are either in [TOML or YAML format][md in astro]. + +3. Sign that blog post with OpenPGP creating a detached signature with the file + extension `.sig` for binary signatures and `.asc` for ASCII armored + signatures, on the same directory as the blog `.md` file: + + gpg -b ./src/content/blog/.md + + Perfer [these][web crypto algs] algorithms. + +4. Commit the new blog post plus the signature. + +5. The `.md` blog post file, its signature, and your public key are now + available to the website user. We can download them, import the key and + verify themselves: + + gpg --import publickey.asc + gpg --search-keys + gpg --recv-keys 0x + gpg --auto-key-locate wkd,keyserver --locate-keys + + gpg --verify ./src/content/blog/.md.sig ./src/content/blog/.md + + The UI will show all the `signer` information from the _frontmatter_ plus, + the commit who created the signature plus the signature of that commit, the + QR code for the public key, download everything as an archive option and a + label based on this: + + - good: signed + verified signature + trust level + - warning: signed + verified signature + untrusted + - warning: signed + verified signature + key revoked + when time of + revocation after time of signature + backdate fake signatures + - error: signed + verified signature + key revoked + date of revocation + + when time of revocation before time of signature + - error: signed + unverifiable + - warning: signed + not recognized + - error: unsigned + +[blog dir]: /src/content/blog "Blogs directory" +[blog template]: /src/content/blog/TEMPLATE "Blog Markdown template" +[web crypto algs]: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign#algorithm "Supported signing algorithms by the Web Crypto API" +[md in astro]: https://docs.astro.build/en/guides/markdown-content/#importing-markdown "Importing Markdown in Astro" -- cgit v1.2.3