encoding.md (2263B)
1 # Key encodings 2 3 Keys can (or will) be encoded in multiple formats. This file shows a list of 4 encodings supported by this program. 5 6 Each key-file must start with a distinct prefix (byte sequence), allowing a 7 different prefix to identify a different type of key encoding. 8 9 A decoded key is either full (public + private half) or public-only. A 10 `NULL` private half means public-only; commands requiring the private half 11 (`sign`) refuse such keys while `verify` accepts them. A lone private half 12 additionally yields its public half via scalar multiplication. 13 14 ## 0x00 15 16 Plain, binary, ed25519. 17 18 Not text-safe. Starts with a 0x00 byte, followed by 32 bytes of the raw public 19 key. Full keys additionally carry 64 bytes of the raw private key after that, 20 so valid sizes are 33 (public-only) or 97 (full) bytes. 21 22 Intended as the first format supported and to be deprecated later. Meant to be 23 simple to code, not to be safe or flexible. 24 25 ## asc 26 27 Ascii-armored raw key bytes, no prefix. A full key emits both a PRIVATE 28 block (64 private bytes) and a PUBLIC block (32 public bytes): 29 30 ``` 31 -----BEGIN SUPERCOP PRIVATE KEY----- 32 <base64, 64 columns> 33 -----END SUPERCOP PRIVATE KEY----- 34 -----BEGIN SUPERCOP PUBLIC KEY----- 35 <base64, 64 columns> 36 -----END SUPERCOP PUBLIC KEY----- 37 ``` 38 39 Public-only keys emit just the PUBLIC block. Labels are namespaced so 40 openssl never mistakes the raw payload for DER/PKCS#8. When both blocks 41 are present, the private block is authoritative and the public block must 42 agree with the derived public half; a corrupt private block fails closed. 43 44 ## hdr 45 46 General-purpose text-protocol header encoding. Byte-identical to what 47 `printkey` outputs: 48 49 ``` 50 public-key: <64 hex> 51 private-key: <128 hex | (no private key)> 52 ``` 53 54 Parsing rules, meant to make integration in other programs easy: 55 56 - Key lines may appear on any line, in any order, surrounded by any other 57 content; unknown labels are ignored. 58 - Labels are case-insensitive, with 0 or more spaces/tabs around the `:`. 59 - A parenthesized value (e.g. `(no private key)`) marks the field absent; a 60 missing `private-key:` line means the same. First valid occurrence wins, 61 malformed hex runs are skipped. 62 - A lone `private-key:` line derives its public half; a file with neither 63 key line is invalid.