=============================================================== /dist/META/ -- introduction =============================================================== End-users download ASF artifacts. An end-user wants to be certain that the artifact is endorsed by the ASF. We assume that the end-user is prepared to trust : -- a ASF company PGP key, -- anything signed by the ASF key, -- and (a priori) nothing else. Each ASF artifact is signed by some release manager [RM]. For example artifact : /dist/PROJ/foo.tar.gz signature : /dist/PROJ/foo.tar.gz.asc signed by : key deadbeefdeadbeef -- some_rm@apache.org Why should an end-user believe that /dist/PROJ/foo.tar.gz is endorsed by the ASF ? For an end-user it is easy to check the signature, and establish that it was created by key deadbeefdeadbeef . For an end-user is almost impossible to establish that (RM) some_rm@apache.org is authorised to release and sign artifact /dist/PROJ/foo.tar.gz. Actually, the end-user doesn't care which RM signed the artifact. The end-user just wants be certain that the artifact is endorsed by the ASF. How do we bridge the gap between "signed by key deadbeefdeadbeef (some_rm@apache.org)" and "endorsed by the ASF" ? We present the end-user with a hierachical model of the ASF : -- the ASF authorises PMC's to release artifacts -- a PMC authorises certain RM's to release certain artifacts The "endorsements" are stored in META files : -- a META file has lines like "key KEY1 signs PATH" ; -- a META file is signed by, say, "KEY2 -- META-SIGNER". -- meaning : META-SIGNER authorises (the owner of) KEY1 to sign artifact PATH, -- as endorsement : META-SIGNER endorses artifact PATH, if signed by KEY1. -- the "endorsements" in a META file are useless, unless the META file is endorsed elsewhere (higher in the tree). Directory /dist/META/ contains the ASF's root-of-authority files. These files authorise /dist/$pmc/META files, which in turn authorise artifacts in /dist/$pmc/ etc. In short, this is how it works : -- /dist/META/ASF is endorsed (signed) by the ASF-key -- /dist/META/ASF endorses /dist/META/ROOT -- /dist/META/ROOT endorses /dist/$pmc/META -- /dist/$pmc/META endorses /dist/$pmc/artifacts -- /dist/$pmc/META endorses /dist/$pmc/sub/META -- /dist/$pmc/sub/META endorses /dist/$pmc/sub/artifacts -- etc Technically : -- Actually, when a META file contains a line like : key KEY signs PATH the PATH is interpreted as a prefix. The line authorises KEY to sign files PATH*. This makes the META files denser, and more resilient to change (the addition/removal of releases). -- The prefix is interpreted relative to the META file, so file /dist/path/to/META authorises KEY to sign files /dist/path/to/PATH* More info : https://checker.apache.org/doc/README.html#ch-meta =============================================================== /dist/META/ -- Files =============================================================== -- ASF-key.txt : public ASF company key 36625D435EF870E1 -- ASF : specifies which keys may sign file ROOT -- ASF.asc : must be created with ASF-key 36625D435EF870E1 -- ROOT : specifies which keys may sign /dist/$pmc/META -- ROOT.asc : must be signed by a key listed in file ASF Aside : It would be more logical to have file /dist/META, /dist/META.asc -- META signed by the company key -- authorising /dist/$pmc/META files The problem with such a setup is that it requires using the company key each time /dist/META changes. To avoid that we could introduce /dist/ROOT, /dist/ROOT.asc, as above, resulting in 4 extra (meta) files in /dist/. To avoid clutter in /dist/, these 4 files are placed in dist/META/, and prefixes in META/ASF, META/ROOT are relative /dist/. =============================================================== /dist/META/ -- How to update META/ROOT =============================================================== File META/ROOT may only be updated by owners of keys as listed in META/ASF. To update META/ROOT, use program 'mk-root'. -- Run 'make init' ; once is ok ; it imports 4 infra keys. -- By default, program 'mk-root' creates file ROOT, with authorisatons for all $pmc/META files where PMC $pmc has a chair with (at least) one registered key. Use file 'config' to modify ; see "mk-root -h". Don't use "pmc $pmc add pmc". -- Updating META/ROOT : On a private host ; create and sign ROOT ; then publish : -- make a new ROOT % cd working copy of /dist/META/ % svn up % make root # this removes ROOT.asc if bad -- sign with your default key : % make sign -- check with : % make vrfy -- commit with : % make commit -- or backout with % make undo To set your default key : -- edit $HOME/.gnupg/gpg.conf -- add a line like : default-key LONG_KEY_ID with LONG_KEY_ID like d91b182c0f85ecd4 =============================================================== /dist/META/ -- mk-root usage =============================================================== Usage: mk-root [-v] [-q] [-d] [-h] [-o out] [-c conf] option v : be verbose option q : be quiet option d : show debug info option h : show help ; exit option o : write $out ; default "ROOT" option c : use config $conf ; default "config" ==================================================================== -- mk-root begins with authorisation for $pmc/META files where $pmc has a chair with registered keys. -- Any additions/deletions must be specified in the $config file. -- On succesful completion, mk-root -- writes file $out [default ROOT] -- removes file $out.asc if "gpg --verify $out.asc $out" fails ==================================================================== config has lines like : pmc $pmc add|del key $key-id # add/del a key pmc $pmc add|del user $user-id # add/del a user pmc $pmc add|del chair # add/del the pmc chair pmc $pmc add|del members # add/del all pmc members pmc $pmc add|del key $key-id # add/del a key aux $path add|del key $key-id # add/del a key aux $path add|del user $user-id # add/del a user