README (3317B)
1 miniroon: minimalist implementation of Macaroon authentication primitive for POSIX systems 2 ========================================================================================== 3 4 Macaroons are simple authentication cookies that allow for attenuation of authority, 5 that is the cookie can be extended by additional restrictions called caveats. 6 7 Miniroon is an implementation of macaroons for UNIX-like systems that strives to be as 8 simple as possible, but no simpler. 9 10 For each miniroon id three pieces of information need to be provided: 11 * secret: random / unguessable 32 bytes used as signature base 12 * command to be executed upon succesful authentication 13 * environment whitelist declaring which environment variables may be modified by the 14 miniroon 15 16 dependencies 17 ------------ 18 19 For building: 20 21 * gcc with C11 standard support 22 * GNU make 23 * skalibs https://skarnet.org/software/skalibs/ 24 25 For development & tests: 26 27 * triehash https://github.com/julian-klode/triehash 28 * Python 3 (no external packages used) 29 30 miniroon wire format 31 -------------------- 32 33 TBD 34 35 miniroon programs and directory structure 36 ----------------------------------------- 37 38 miniroon <-- catalog directory 39 ├── example1 <-- run directory 40 │ ├── run 41 │ ├── secret 42 │ └── verify 43 └── example2 <-- another run directory 44 ├── run 45 ├── secret 46 └── verify 47 48 The `miniroon-read` command takes single argument that is the catalog directory to use, 49 eg. `miniroon-read ./data/miniroon`. 50 The `miniroon-read` program is expected to be launched from `s6-sudo`, via OpenSSH 51 `ForceCommand` option or otherwise from other security domain but inheriting required 52 access rights. 53 It reads miniroon wire format on stdin, parses it's header and if it contains recognized 54 `version` and `id` it changes into run directory with the same name as the `id` in the 55 catalog directory. 56 The stdin file descriptor is then closed, but stdout and stderr are left intact and free 57 to use by application being run. 58 It then executes into `verify` file in the run directory and passess it arguments 59 that should be given to `miniroon-verify` program. 60 The `verify` file is supposed to set up environment variables that may be changed and 61 execute `miniroon-verify` with the same arguments it got. 62 Similarly to `s6-sudod` only the environment variables which are present but empty can 63 be changed by the provided miniroon. 64 Commonly the verify file would look something like: 65 66 #!/bin/sh 67 exec env var1= var2= var3= miniroon-verify "$@" 68 69 The `miniroon-verify` program then does the actual verification of full miniroon 70 including the provided signature verifying each part of miniroon starting with the 71 content of the `secret` file in the rundir. 72 If verification passess the `run` file in the run directory is then executed. 73 74 TODO: document `invoke-once` and `revoke` miniroon modes. 75 76 references 77 ---------- 78 79 The original macaroon paper: https://research.google.com/pubs/archive/41892.pdf 80 @inproceedings{41892, 81 title = {Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud}, 82 author = {Arnar Birgisson and Joe Gibbs Politz and Úlfar Erlingsson and Ankur Taly and Michael Vrable and Mark Lentczner}, 83 year = {2014}, 84 booktitle = {Network and Distributed System Security Symposium} 85 }