---
title: "OpenPGP armor"
description: "The -----BEGIN PGP----- blocks from RFC 9580. Wrap bytes in armor or pull them back out with the label and headers intact"
canonical_url: "https://encodings.agntn.dev/guide/armor"
---
# OpenPGP armor

> The -----BEGIN PGP----- blocks from RFC 9580. Wrap bytes in armor or pull them back out with the label and headers intact

## Base64 in a nice suit

That PGP key you once pasted into a form? Armor. It's base64 with a `-----BEGIN PGP MESSAGE-----` line on top, an END line below and a few `Name: value` headers if somebody felt chatty. Nothing is encrypted by the armor itself. It just keeps binary packets alive in an email.

```ts
import { armor } from "@agntn/encodings";

const block = armor.encode(new TextEncoder().encode("Hello, armor"), {
  label: "MESSAGE",
  headers: [["Comment", "not encrypted, just wrapped"]],
});
// -----BEGIN PGP MESSAGE-----
// Comment: not encrypted, just wrapped
//
// SGVsbG8sIGFybW9y
// -----END PGP MESSAGE-----

armor.decode(block);
// { label: "MESSAGE", headers: [["Comment", "not encrypted, just wrapped"]],
//   bytes: Uint8Array(12), checksum: "absent" }
```

The label is whatever follows `BEGIN PGP `. `MESSAGE`, `PUBLIC KEY BLOCK`, `SIGNATURE`, or your own. Headers are pairs, in order, so a repeated `Comment` stays repeated. Lines come out at 64 characters, the way GnuPG writes them.

## What's that `=` line above END?

Older blocks carry a CRC24 there, a 24-bit checksum of the bytes. RFC 9580 says to stop writing it, and never to reject a block over it. So `encode` leaves it out unless you ask.

```ts
armor.encode(new TextEncoder().encode("Hello, armor"), { label: "MESSAGE", checksum: true });
// -----BEGIN PGP MESSAGE-----
//
// SGVsbG8sIGFybW9y
// =o0JO
// -----END PGP MESSAGE-----
```

And `decode` never throws on it. A wrong one shows up as `checksum: "mismatch"` next to perfectly good bytes. Want to warn somebody that the text got changed or cut? Go ahead. The bytes are still yours to use.

## Armor from the wild

Real armor arrives pasted, forwarded and a bit mangled. `decode` takes it the way it comes:

- text around the block, like the rest of an email,
- CRLF line ends and indented lines,
- a lost blank line under the headers,
- spaces and blank lines inside the base64.

Two blocks in one text? You get the first one. Pass `label: "SIGNATURE"` and it skips to the one you want. A cleartext signed message isn't armor at all, only its signature block is. So `decode` steps over the `SIGNED MESSAGE` frame and hands you the `SIGNATURE`. Checking that signature is a job for [@agntn/keys](https://github.com/agntn/keys).

What it won't take is a block with no END line, a checksum line with data under it, or data that isn't base64. Each one is a `DecodeError`. A label in lowercase, or one with `PGP` already in it, is an `InvalidOptionError` that tells you what to pass instead.

## Where it lives

`decode` hands back a label and headers along with the bytes, and nothing in the registry does that. So `armor` sits outside it, like [RLP](https://encodings.agntn.dev/guide/rlp) and the [code pages](https://encodings.agntn.dev/guide/code-pages). The subpath is `@agntn/encodings/armor`. No CLI command and no agent tool yet, just the two functions.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
