Browse code
Improve README.
| ... | ... |
@@ -1 +1,82 @@ |
| 1 |
-yamltab converts keytabs to YAML/JSON and the other way around. |
|
| 1 |
+ |
|
| 2 |
+# yamltab |
|
| 3 |
+ |
|
| 4 |
+yamltab converts Kerberos keytabs to YAML/JSON and the other way around. |
|
| 5 |
+ |
|
| 6 |
+## Keytab input, YAML/JSON output |
|
| 7 |
+ |
|
| 8 |
+Given a keytab file, yamltab will output a YAML representation of its contents, suitable for human edition |
|
| 9 |
+ |
|
| 10 |
+```console |
|
| 11 |
+$ yamltab example.keytab |
|
| 12 |
+version: 2 |
|
| 13 |
+entries: |
|
| 14 |
+ - spn: HTTP/application.example.com@EXAMPLE.COM |
|
| 15 |
+ principal: |
|
| 16 |
+ name_type: KRB5_NT_PRINCIPAL |
|
| 17 |
+ components: |
|
| 18 |
+ - HTTP |
|
| 19 |
+ - application.example.com |
|
| 20 |
+ realm: EXAMPLE.COM |
|
| 21 |
+ kvno: 42 |
|
| 22 |
+ date: '2020-04-28T14:04:12Z' |
|
| 23 |
+ enctype: AES256_CTS_HMAC_SHA1_96 |
|
| 24 |
+ key: 0123456789abcdeffedcba9876543210abcdeffedcba9876543210abcdef1234 |
|
| 25 |
+``` |
|
| 26 |
+ |
|
| 27 |
+JSON output is also supported: |
|
| 28 |
+```console |
|
| 29 |
+$ yamltab -f json example.keytab | jq '.entries[0].principal.realm' |
|
| 30 |
+"EXAMPLE.COM" |
|
| 31 |
+``` |
|
| 32 |
+ |
|
| 33 |
+## Data layouts |
|
| 34 |
+yamltab offers several "data layouts" for its YAML/JSON output: |
|
| 35 |
+ |
|
| 36 |
+ - **raw** simply reflects the raw, complete binary structure: it reflects records and holes, tails (i.e. data in a record beyond its entry length) and exposes raw values (name types, timestamps, encryption types, etc.), without any kind of interpretation. |
|
| 37 |
+ - **full** is the same structure as *raw* with additional properties for the sake of readability. |
|
| 38 |
+ - **simple**, shown above, is the default format; it aims at exposing everything that matters in the keytab in a user-friendly way. |
|
| 39 |
+ |
|
| 40 |
+```console |
|
| 41 |
+$ yamltab -l raw -f json example.keytab | jq '.records[0].entry.timestamp' |
|
| 42 |
+1588082652 |
|
| 43 |
+$ yamltab -l full -f json example.keytab | jq '.records[0].entry.date' |
|
| 44 |
+"2020-04-28T14:04:12Z" |
|
| 45 |
+$ yamltab -l simple -f json example.keytab | jq '.entries[0].date' |
|
| 46 |
+"2020-04-28T14:04:12Z" |
|
| 47 |
+``` |
|
| 48 |
+ |
|
| 49 |
+## YAML/JSON input, keytab output |
|
| 50 |
+yamltab also offers the ability to convert YAML/JSON input into a binary keytab: |
|
| 51 |
+```console |
|
| 52 |
+$ yamltab example.keytab.yaml | file - |
|
| 53 |
+/dev/stdin: Kerberos Keytab file, realm=EXAMPLE.COM, principal=HTTP/application.example.com, type=1, date=Tue Apr 28 14:04:12 2020, kvno=42 |
|
| 54 |
+``` |
|
| 55 |
+It supports all three data layouts: *raw* is useful to control every detail of the keytab; *full* is processed the same way. Internally, *simple* input is converted to the *full* data layout; the resulting structure can be inspected using `--simple-to-full`. |
|
| 56 |
+ |
|
| 57 |
+## Other options |
|
| 58 |
+`--names-types` and `--enc-types` list known name and encryption types, respectively. They can be combined with `--format`: |
|
| 59 |
+```console |
|
| 60 |
+$ ./yamltab -f json --enc-types | jq '.AES256_CTS_HMAC_SHA1_96' |
|
| 61 |
+18 |
|
| 62 |
+``` |
|
| 63 |
+`--v1-endianness` exists as a vague attempt to support keytab v1 format. However, keytab v2 has been around since 1992 and real-life keytab v1 files are nowhere to be found. Consequently, keytab v1 support is completely untested and very likely to result in a stacktrace or absurd output. |
|
| 64 |
+ |
|
| 65 |
+## Keytab edition |
|
| 66 |
+Since yamltab can convert a keytab to YAML and this YAML representation back into a keytab, then it should be easy to assemble a wrapper that allows interactive edition of a keytab file as YAML by invoking your favourite editor. This is what the `keytab-editor` script does. |
|
| 67 |
+ |
|
| 68 |
+## Subtleties |
|
| 69 |
+The simple format is liable to expose two overlapping properties: `spn` and `principal`. (the former is convenient, the latter is comprehensive). When processing its YAML input, yamltab takes `principal` into account and ignores `spn`... unless `principal` happens to be missing, in which case yamltab attempts to convert `spn` into a KRB5_NT_PRINCIPAL principal. |
|
| 70 |
+ |
|
| 71 |
+`name_type_raw`, `enc_type_raw` and `timestamp` override `name_type`, `enc_type` and `date` respectively. |
|
| 72 |
+ |
|
| 73 |
+Dates handling is NOT clever. Stick to the `YYYY-mm-DDTHHMMSSZ` format. That said, it is possible to write `date: now` in simple mode. |
|
| 74 |
+ |
|
| 75 |
+In *simple* mode,`kvno_in_tail: True` can be used to force storage of the key version number as a 32-bit unsigned integer in the tail (i.e. after the entry). `extra_tail` can be used to inject arbitrary data in the tail. |
|
| 76 |
+In *full* mode, the following keys strive to reflect kvno: |
|
| 77 |
+ |
|
| 78 |
+ - `kvno`: 8-bit key version number found in the entry, always present; |
|
| 79 |
+ - `tail_kvno`: 32-bit key version number found right after the entry, present only if actually found; |
|
| 80 |
+ - `actual_kvno`: kvno value that matters, always present. |
|
| 81 |
+ |
|
| 82 |
+Limitations: yamltab spares you the pain of hex-editing keytab files; however, it offers no encryption-related features. Keys are always handled as hexadecimal blobs, and password hashing is simply not supported. |