Next: , Previous: , Up: API  


1.2 (bewaking cli)

1.2.1 Procedures

Procedure: run args

Run the bewaking command-line interface with args (a list of strings, without the program name). Returns the process exit code: 0 on success and 1 on any error or usage problem.

1.2.2 Variables

Variable: usage
"bewaking — encrypted tokens, sealed objects and password tools\n\nUsage:\n  bewaking token generate   [options]\n  bewaking token decrypt    [options]\n  bewaking token inspect    [options]\n  bewaking object encrypt   [options]\n  bewaking object decrypt   [options]\n  bewaking password strength [PASSWORD]\n  bewaking password generate [options]\n  bewaking help\n\nKeys (required for token/object commands, unless --keyring is given):\n  --encryption-key KEY          inner AES-256 key (1st seal)\n  --encryption-key-file FILE    read the inner key from FILE\n  --signing-key KEY             outer AES-256 key (2nd seal)\n  --signing-key-file FILE       read the outer key from FILE\n  --keyring FILE                Scheme alist of key-id -> keys, for rotation\n  --key-id LABEL                key id embedded when sealing (default \"default\")\n  Environment fallbacks: BEWAKING_ENCRYPTION_KEY, BEWAKING_SIGNING_KEY\n\nRotation metadata (recorded in the sealed header and covered by the cipher tag):\n  --ttl-seconds N               seal data that expires N seconds from now\n  --expires-at TS               seal data that expires at an absolute Unix time\n  --max-age-seconds N           refuse data sealed longer ago than N seconds\n  --allow-expired               open expired data anyway (audit/recovery only)\n\nKey derivation (sealing only; opening reads it back from the data itself):\n  --kdf NAME                    pbkdf2 (default) or argon2id\n  --kdf-memory-kib N            Argon2id memory cost in KiB (default 65536)\n  --kdf-iterations N            Argon2id passes (default 3)\n  --kdf-parallelism N           Argon2id lanes (default 1)\n  Argon2id requires libgcrypt 1.11 or newer. The cost is per AES layer and a\n  token has two, so sealing and opening each derive twice: 64 MiB with 3\n  passes is around 90 ms per derivation, 8 MiB with 1 pass around 3 ms.\n  PBKDF2 takes no parameters, because the OpenSSL-compatible format it\n  produces has nowhere to record them.\n\nA keyring file has the shape (not-before/not-after are optional rotation\nwindows; using a key outside its window is refused):\n  ((\"2026a\" (encryption-key . \"e1\") (signing-key . \"s1\"))\n   (\"2025b\" (encryption-key . \"e0\") (signing-key . \"s0\")\n            (not-after . 1790000000)))\n\ntoken generate:\n  --owner-details FILE          owner alist read from FILE (alternative below)\n  --owner-id ID                 owner id (required unless --owner-details)\n  --owner-email EMAIL           owner email\n  --owner-name NAME             owner name\n  --permissions a,b,c           comma-separated permission symbols\n  --validity-seconds N          token lifetime (default 604800)\n\ntoken decrypt:\n  --token TOKEN                 token string\n  --token-file FILE             read the token from FILE\n\ntoken inspect:\n  --token TOKEN | --token-file FILE\n                                print the envelope metadata (version, key id,\n                                created-at, expiry) without needing any key\n\nobject encrypt / object decrypt:\n  --input FILE                  read the payload/sealed string from FILE\n                                (default: standard input)\n\npassword strength:\n  PASSWORD (positional) or one line on standard input\n\npassword generate:\n  --length N                    password length (default 24)\n  --no-symbols                  exclude symbol characters\n\nExamples:\n  bewaking token generate --owner-id 42 --owner-name Joe \\\n      --permissions read,write --encryption-key \"$K1\" --signing-key \"$K2\"\n  bewaking token decrypt --token \"$TOKEN\" \\\n      --encryption-key \"$K1\" --signing-key \"$K2\"\n  echo '((name . Joe) (score . 7))' | bewaking object encrypt \\\n      --encryption-key \"$K1\" --signing-key \"$K2\"\n  bewaking token generate --owner-id 42 --kdf argon2id \\\n      --kdf-memory-kib 8192 --encryption-key \"$K1\" --signing-key \"$K2\"\n  bewaking password generate --length 32\n"

Next: (bewaking crypto), Previous: (bewaking bewaking), Up: API