python-gnupg audit

`%make-dns-cert -n danm.prime.gushi.org. -k 624BB249.pub.bin + danm.prime.gushi.org. TYPE37 \# 1298 0003 0000 00 9901A20439D8DAF1110400F770EC6AA006076334BEC6DB6FBB237DC194BC0AB8 + 302C8953F04C28FC2085235D4F10EFA027234FBD63D142CCADD5213AD2B79A22C89ED9B4138370D8220D0F987F993A5364A4A7AC3D42F3765C384 + 71DDD0FF3372E4AE6F7BEE1E18EF464A0BEB5BBE860A08238891455EBE7CB53D567E981F78ADBD263206B0493ADCB74DD00A0FF0E9A1CD245415E + CEF59435162AFCE4CDD14BC70400EA38FF501256E773DEA299404854D99F4EDB2757AA911A9C77C68AB8D6622E517A556C43D21F0523C568F016C + D0DB89EF435F0D53B4E07434213F899E6578955DC2C147931E7B6901C9FD8A02705417D69A879B3CC196D2AC2EAEF311192EE89ABAF5A60942167 + B4625735FCBDFB5DE0E3AC1236A53FA4D7CDD7D75F5DE85AF50400867D9546B28B79AF10541053CF4AB06A6171BFD21458BFD12AF1AE2B2401CAD + 8851661F8AF6602F80EDAC99C79616BE1F910F4156242003779C68D7A079A8B18F89DD293E1B247E7420471300A4A0730AA61DE281CCC211FC405 + A0A8A79877999FF9042AD892AB927DA371E8883BBB370AB7A97841408C3486BB18598CF2559BB42844616E69656C20502E204D61686F6E6579203 + C64616E6D407072696D652E67757368692E6F72673E884E04101102000E050239D8DAF1040B030102021901000A0910FBBE5A30624BB249FA2E00 + 9B057503ED498695AE5ED73CA1B98EBAEE13F717E500A0921E0D92724459100266FEBBC29E911C8B0F530BB43244616E69656C204D61686F6E657 + 920285365636F6E6461727920456D61696C29203C67757368694067757368692E6F72673E8860041311020020050245D49FD7021B23060B090807 + 030204150208030416020301021E01021780000A0910FBBE5A30624BB249158400A082C8AF43DA8B85F740D6B1A6E9FF0B4490520B8C00A08F77D + 21FBF86C842963E8090DC0646D1DD7F95C9B9020D0439D8DAF4100800F64257B7087F081772A2BAD6A942F305E8F95311394FB6F16EB94B3820DA + 01A756A314E98F4055F3D007C6CB43A994ADF74C648649F80C83BD65E917D4A1D350F8F5595FDC76524F3D3D8DDBCE99E1579259CDFDB8AE744FC + 5FC76BC83C5473061CE7CC966FF15F9BBFD915EC701AAD35B9E8DA0A5723AD41AF0BF4600582BE5F488FD584E49DBCD20B49DE49107366B336C38 + 0D451D0F7C88B31C7C5B2D8EF6F3C923C043F0A55B188D8EBB558CB85D38D334FD7C175743A31D186CDE33212CB52AFF3CE1B1294018118D7C84A + 70A72D686C40319C807297ACA950CD9969FABD00A509B0246D3083D66A45D419F9C7CBD894B221926BAABA25EC355E9320B3B00020207FF5E1A3C + C5DA00E1E94EC8EF6C7FE9B49D944C71D8BBC817DD8E64A7344B9E48392E0B833B3B1DB7E6D5A38BE2826DEF0060F78C6417871EAF1CFBCBC47D2 + 7E93718D975E0A3A36D868C021D6B771740CE2918307D69D614BBF0632DC31932EA31397A7F3B04618C9A76C2F38265C7037E303EDD8AEF03D069 + 208E3FE9C4EA77D83E6311ED36C013D58C54E914B263A459E22D463A0288510C4752B99C163EEA0A55686979691AB0D9F9AA0C06C834446D7A723 + EC534D819301382621ACF8930C74E9FD28C8797718AEC2C30CF601E24194B799234104A3D6239657B1D4AD545BDAA637F61541435CB51B4D138FB + F55E1A9FD2EED860E4459D6795B6FCCA23155A8846041811020006050239D8DAF4000A0910FBBE5A30624BB249415A009E37BCFDC64E76CBF6A86 + 82B85EA161BD1DFB793DF00A0C471BC7B9723535CD855D8FF1EB93F01E251B698 + % + +The program prints that all on **one line**. + +Immediately, we notice a few things. + +* The record type isn't "CERT", it's "TYPE37". This confused me for a while until I discovered [RFC3597](http://www.faqs.org/rfcs/rfc3597.html) Basically, it's a way that a DNS server can handle a resource record it doesn't know about, by giving it some special fields like the "#", as well as a length (which is the 1298 you see there). + +* The rest of the record is on one line. I wrapped it for the purposes of brevity. If I were using this in a zonefile, I would need to be careful that I wrapped it on a byte-boundary (every two characters is a byte). If I miss the boundary, named will refuse to load it, dnssec-signzone won't touch it, etc. + +4. So the thing is ugly and you don't want to touch it. The easiest way to work with it is to drop all that into a file: + + %make-dns-cert -n danm.prime.gushi.org. -k 624BB249.pub.bin > 624BB249.big.cert + + +5. And then either read it into your editor, or tack it on like this: + + %cat 624BB249.big.cert >> your.zonefile + +Be sure to make a backup first. Either way, you never have to copy/paste the raw hex and worry about newlines being inserted where you don't want them. + +6. Before you reload your zone, you might want to use named-checkzone on it first: + + prime# named-checkzone gushi.org gushi.org.hosts + zone gushi.org/IN: loaded serial 2009102909 + OK + prime# + +7. Voice of experience: You may want to dial the TTL (which controls how long servers will cache your data) way down on the record above. It's not hard, just put a number before the TYPE37, with a space, i.e: + + danm.prime.gushi.org. 30 TYPE37 + +This way if it all goes terribly wrong, or you need to make changes, it won't be cached for very long. + +8. If it looks okay, bump your serial number and reload. + +#### Testing + +1. As above, you can dig, but you won't be able to easily read the results: + + prime# dig +short danm.prime.gushi.org CERT + ;; Truncated, retrying in TCP mode. + + +PGP 0 0 +mQGiBDnY2vERBAD3cOxqoAYHYzS+xttvuyN9wZS8CrgwLIlT8Ewo/CCF +I11PEO+gJyNPvWPRQsyt1SE60reaIsie2bQTg3DYIg0PmH+ZOlNkpKes +PULzdlw4Rx3dD/M3Lkrm977h4Y70ZKC+tbvoYKCCOIkUVevny1PVZ+mB +94rb0mMgawSTrct03QCg/w6aHNJFQV7O9ZQ1Fir85M3RS8cEAOo4/1AS +Vudz3qKZQEhU2Z9O2ydXqpEanHfGirjWYi5RelVsQ9IfBSPFaPAWzQ24 +nvQ18NU7TgdDQhP4meZXiVXcLBR5Mee2kByf2KAnBUF9aah5s8wZbSrC +6u8xEZLuiauvWmCUIWe0Ylc1/L37XeDjrBI2pT+k183X119d6Fr1BACG +fZVGsot5rxBUEFPPSrBqYXG/0hRYv9Eq8a4rJAHK2IUWYfivZgL4DtrJ +nHlha+H5EPQVYkIAN3nGjXoHmosY+J3Sk+GyR+dCBHEwCkoHMKph3igc +zCEfxAWgqKeYd5mf+QQq2JKrkn2jceiIO7s3CrepeEFAjDSGuxhZjPJV +m7QoRGFuaWVsIFAuIE1haG9uZXkgPGRhbm1AcHJpbWUuZ3VzaGkub3Jn +PohOBBARAgAOBQI52NrxBAsDAQICGQEACgkQ+75aMGJLskn6LgCbBXUD +7UmGla5e1zyhuY667hP3F+UAoJIeDZJyRFkQAmb+u8KekRyLD1MLtDJE +YW5pZWwgTWFob25leSAoU2Vjb25kYXJ5IEVtYWlsKSA8Z3VzaGlAZ3Vz +aGkub3JnPohgBBMRAgAgBQJF1J/XAhsjBgsJCAcDAgQVAggDBBYCAwEC +HgECF4AACgkQ+75aMGJLskkVhACggsivQ9qLhfdA1rGm6f8LRJBSC4wA +oI930h+/hshClj6AkNwGRtHdf5XJuQINBDnY2vQQCAD2Qle3CH8IF3Ki +utapQvMF6PlTETlPtvFuuUs4INoBp1ajFOmPQFXz0AfGy0OplK33TGSG +SfgMg71l6RfUodNQ+PVZX9x2Uk89PY3bzpnhV5JZzf24rnRPxfx2vIPF +RzBhznzJZv8V+bv9kV7HAarTW56NoKVyOtQa8L9GAFgr5fSI/VhOSdvN +ILSd5JEHNmszbDgNRR0PfIizHHxbLY7288kjwEPwpVsYjY67VYy4XTjT +NP18F1dDox0YbN4zISy1Kv884bEpQBgRjXyEpwpy1obEAxnIByl6ypUM +2Zafq9AKUJsCRtMIPWakXUGfnHy9iUsiGSa6q6Jew1XpMgs7AAICB/9e +GjzF2gDh6U7I72x/6bSdlExx2LvIF92OZKc0S55IOS4Lgzs7Hbfm1aOL +4oJt7wBg94xkF4cerxz7y8R9J+k3GNl14KOjbYaMAh1rdxdAzikYMH1p +1hS78GMtwxky6jE5en87BGGMmnbC84JlxwN+MD7diu8D0Gkgjj/pxOp3 +2D5jEe02wBPVjFTpFLJjpFniLUY6AohRDEdSuZwWPuoKVWhpeWkasNn5 +qgwGyDREbXpyPsU02BkwE4JiGs+JMMdOn9KMh5dxiuwsMM9gHiQZS3mS +NBBKPWI5ZXsdStVFvapjf2FUFDXLUbTROPv1Xhqf0u7YYORFnWeVtvzK +IxVaiEYEGBECAAYFAjnY2vQACgkQ+75aMGJLsklBWgCeN7z9xk52y/ao +aCuF6hYb0d+3k98AoMRxvHuXI1Nc2FXY/x65PwHiUbaY + + +It's still ugly, but it's not AS ugly because it's base64, which includes +spaces, at least, and is easier to search for a pattern. Base64 can also be +easily wrapped on any boundary, which is nice. + +You can run your existing exported key through a base64 converter, like the +one built into the openssl binary, if you want to compare: + + %cat 624BB249.pub.bin | openssl enc -base64 + mQGiBDnY2vERBAD3cOxqoAYHYzS+xttvuyN9wZS8CrgwLIlT8Ewo/CCFI11PEO+g + JyNPvWPRQsyt1SE60reaIsie2bQTg3DYIg0PmH+ZOlNkpKesPULzdlw4Rx3dD/M3 + Lkrm977h4Y70ZKC+tbvoYKCCOIkUVevny1PVZ+mB94rb0mMgawSTrct03QCg/w6a + (...etc...) + OPv1Xhqf0u7YYORFnWeVtvzKIxVaiEYEGBECAAYFAjnY2vQACgkQ+75aMGJLsklB + WgCeN7z9xk52y/aoaCuF6hYb0d+3k98AoMRxvHuXI1Nc2FXY/x65PwHiUbaY + + +Now, while you could compare things byte-by-byte here, what I've done as a +"casual check" is just pick random strings in the text and see if they match +up. For example, you can see that "reaIsie2" is present in both. They both +start with and end with similar strings on every line. The real test, of +course, is to see if GPG recognizes it as a valid key. + +By the way, since I use DNSSEC, dnssec-signzone rewrites this record into the +proper "presentation format" for me, which is base64. If you want a similar +function, you can use named-compilezone to get some of the same effects, or +you can use the shell script I provide later in this document, with which you +don't even need make-dns-cert. + +2. Testing with gpg + +As above, the command to test this is remarkably simple: + + %rm /tmp/gpg-* + %echo "foo" | gpg --no-default-keyring --keyring /tmp/gpg-$$ --encrypt --armor --auto-key-locate cert -r danm@prime.gushi.org + gpg: keyring `/tmp/gpg-39996' created + gpg: key 624BB249: public key "Daniel P. Mahoney <danm@prime.gushi.org>" imported + gpg: Total number processed: 1 + gpg: imported: 1 + gpg: automatically retrieved `danm@prime.gushi.org' via DNS CERT + gpg: DE20C529: There is no assurance this key belongs to the named user + pub 2048g/DE20C529 2000-10-02 Daniel P. Mahoney <danm@prime.gushi.org> + Primary key fingerprint: C206 3054 5492 95F3 3490 37FF FBBE 5A30 624B B249 + Subkey fingerprint: CE40 B786 81E2 5CB9 F7D3 1318 9488 EB58 DE20 C529 + It is NOT certain that the key belongs to the person named + in the user ID. If you *really* know what you are doing, + you may answer the next question with yes. + Use this key anyway? (y/N) y + -----BEGIN PGP MESSAGE----- + Version: GnuPG v1.4.10 (FreeBSD) + hQIOA5SI61jeIMUpEAf/Sx7MKWm+e9EpUTSrDaBp4nJfDcBeqbYJulPRbDZz7eVW + 2+ol6sG0jWjuirbG1YppZccEr9mgqaQujdSXb/bleD8POS0TEWuf3aPswFQvHf90 + NLEzHt6BnfLoeobXXxyCflNaGX8zW+XgJtwZqAc2+jietuz8MOUhrf5m17CsW/wZ + IuEqwaek+K1irJp+w3rhaE08Jzb/S4CCifeW9J3mK57chQoPOu7Nz3rY666YKp/3 + 9T9StOgmFiNpvtFPNy4N7hHMHvbQwRsKlnkl+a7n0Aq2+OF4d1+/k2EE4uSGgcz0 + oHvee8DnuOx3P92mO4Jz5/0O0lwBD7I51iOjzUurTAgAiIM5sHV8/QFCVzH9Ule+ + gd8Wo5momcphkU/AXpce5Xgi/Vm4oGQ0x0queii8afUrzkpeN5SuwgQfAdOPiXW5 + 2bo527jBllxOxjeBasfky82XheTnLzbAQNvQNTEM9zE7zCl1LQJUZEJ1hVzcOevI + s+cm/AaGII9VkrAtSt3aLSRZuRJHFmhGvYd2Hz5WzcV1YFjXXP1eLwfetDBlaeB9 + /K5v4hZBkIZPbHX0DcLVrP96mCIT4wCBYSJw+I6n0E6Fz3IfybQG2HMfqWp966/c + 00ijx/aRDh42Dr/fTropuzzFzQr7weYDa1JnN3Zoftv6Zb/n+NcrmMiDCH8jJV6E + uMkaeeB5Mv7ssDQ9kPhO989CHFcznrE1lgOxjX8= + =NTLY + -----END PGP MESSAGE----- + +Okay, as above, try to decrypt that with your private key. + +### IPGP CERT Records + +Also known as: The "little" or "short" CERT record. (These terms are purely my +own). + +Relevant RFCs: [RFC 2538](http://www.faqs.org/rfcs/rfc2538.html), +[RFC 4398](http://www.faqs.org/rfcs/rfc4398.html), specifically sections 2.1 +and 3.3 + +IPGP certs are interesting. It's basically the same pieces of infomation that +are in the PKA record, as above, except that it's supported by an RFC. +Despite the RFC compliance, I am not sure if any non-gpg client knows to look +for them. However, because it's a DNS cert, make-dns-cert encodes the +information in binary, and your DNS server will see it in base64. So +verifying it visually is harder than verifying either of the above. + +#### Advantages + +* Small, easy-to-transmit records. +* Can use the same uri as the PKA record. + +#### Disadvantages + +* Relies on the URI scheme. I haven't yet been able to get a definitive list + of what uri schemes are supported, although I've seen http and finger. I've + also seen reports that unless gpg is compiled against curl, http 1.1 is not + supported (what this actually means is that any host that supports SSL will + probably work, because of some of the nuances of SSL). +* With PGP certs and IPGP certs, GPG will only parse the first key it gets, so + if you publish both, and one doesn't work, there's no failover. I've argued + that this should be fixed. +* Requires make-dns-cert, which is not built in GPG by default. (But see "A + Better Way" below) +* Requires publication in your main DNS zone. +* Despite being RFC compliant, GPG has additional trust vectors for PKA but + not this, despite the fact that they share basically the same information. +* Harder to verify with dig. + +#### Howto + +1. Note that some of these steps are redundant. If you're already doing a PKA + key, skip to step 5. + +2. Dig: + + %gpg --list-keys danm@prime.gushi.org + Warning: using insecure memory! + pub 1024D/624BB249 2000-10-02 <-- I'm going to use this one. + uid Daniel P. Mahoney <danm@prime.gushi.org> + uid Daniel Mahoney (Secondary Email) <gushi@gushi.org> + sub 2048g/DE20C529 2000-10-02 + pub 1024R/309C17C5 1997-05-08 + uid Daniel P. Mahoney <danm@prime.gushi.org> + +3. Export the key to a file (I use keyid.pub.asc, but it can be anything) + + %gpg --export --armor 624BB249 > 624BB249.pub.asc + Warning: using insecure memory! + % + +4. Get the fingerprint for your key: + + %gpg --list-keys --fingerprint 624BB249 + gpg: WARNING: using insecure memory! + gpg: please see http://www.gnupg.org/faq.html for more information + pub 1024D/624BB249 2000-10-02 + Key fingerprint = C206 3054 5492 95F3 3490 37FF FBBE 5A30 624B B249 <-- That bit is your fingerprint. + uid Daniel P. Mahoney <danm@prime.gushi.org> + uid Daniel Mahoney (Secondary Email) <gushi@gushi.org> + sub 2048g/DE20C529 2000-10-02 + +5. As above, run make-dns-cert. This time we use the -n, -f, and -u options: + + %make-dns-cert -n danm.prime.gushi.org. -f C2063054549295F3349037FFFBBE5A30624BB249 -u http://prime.gushi.org/danm.pubkey.txt + danm.prime.gushi.org. TYPE37 \# 64 0006 0000 00 14 C2063054549295F3349037FFFBBE5A30624BB249 687474703A2F2F7072696D652E67757368692E6F72672F64616E6D2E7075626B65792E747874 + % + + +6. Put the above in DNS. All on one line. Optionally add a TTL. + +7. IMPORTANT: make sure you don't have any other CERT records with the same + label (i.e. a "big" cert, as above). While it won't break things, you have + no control over which (of multiple) people will get. + +8. Reload your zone, and test. Testing will probably look VERY MUCH like the + above, but here are the steps anyway: + +#### Testing + +1. Dig: + + %dig +short danm.prime.gushi.org CERT + 6 0 0 FMIGMFRUkpXzNJA3//u+WjBiS7JJaHR0cDovL3ByaW1lLmd1c2hpLm9y Zy9kYW5tLnB1YmtleS50eHQ= + +Sadly, I haven't come across an easy way to decipher it yet, but there's +always gpg. + +2. GPG: + +Since we're fetching the same kind of record, the command is exactly the same +as before: + + %echo "foo" | gpg --no-default-keyring --keyring /tmp/gpg-$$ --encrypt --armor --auto-key-locate cert -r danm@prime.gushi.org + gpg: WARNING: using insecure memory! + gpg: please see http://www.gnupg.org/faq.html for more information + gpg: keyring `/tmp/gpg-39996' created + gpg: requesting key 624BB249 from http server prime.gushi.org + gpg: key 624BB249: public key "Daniel P. Mahoney <danm@prime.gushi.org>" imported + gpg: public key of ultimately trusted key CF45887D not found + gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + gpg: Total number processed: 1 + gpg: imported: 1 + gpg: automatically retrieved `danm@prime.gushi.org' via DNS CERT + gpg: DE20C529: There is no assurance this key belongs to the named user + pub 2048g/DE20C529 2000-10-02 Daniel P. Mahoney <danm@prime.gushi.org> + Primary key fingerprint: C206 3054 5492 95F3 3490 37FF FBBE 5A30 624B B249 + Subkey fingerprint: CE40 B786 81E2 5CB9 F7D3 1318 9488 EB58 DE20 C529 + It is NOT certain that the key belongs to the person named + in the user ID. If you *really* know what you are doing, + you may answer the next question with yes. + Use this key anyway? (y/N) y + -----BEGIN PGP MESSAGE----- + Version: GnuPG v1.4.10 (FreeBSD) + hQIOA5SI61jeIMUpEAgApZurJi3hZmDaUFjB2j93eX/lTl96xq6T//sz6nT6jcTx + IPnq1RN8IrIQPjDBByHdqOZBT5hhblr9xi7NKIIv3W4q4L0z0fJx7NERPZNvn/H0 + DkTwfDgAvCRxcKjenpLSwKZFwLjyfS7wjlDr3HFX7Tila0hbzplHslvgTE0QMcd7 + 7oNmEyOL3z+yZr/afQGp2wpzDv4YB9zOiNHcHcenqX0yrtiqKozZ9VAldi53rb/q + f38lwInbveyAcEQkE2iFwhRsbMR4VLcsBoxY6D9brsBprt23ey8Rnv+bQ9IAR0VN + /WYzU4zUUqb8HmpNFXQLEgH8A2BENw+bxkVYHjSfWQf/cBSGAzfBQQVJ7qp4tN0Z + FRVe51dokbU4NM9tGBdCzFHWARVkQX/Ulekd4F3sxBR/sum1UOT2xl2THVBz7/Pq + UCrTRPA0uH4dIbL5JpfGZhqsJ079+wmUWUtJIiO2wXi7ePEA/DrBC6p7jlmjyYN/ + AeSKcPoTeLX+zryV5bECx4RO6S56EEcy0Ns0pASGMsgUnKL6Adrv3Y6ea3ZAOQMn + H9Uo28BKTKNUvUaBpN8cV8jIbKYPPW9i04kvEQRqs5rdamERCY1vVTqYTrcLsNqz + fF3KopX+V82X1oE2QuGdFfd8mK57ZXJL3VRUrfohQjhfYNKzougiP46rQQv79MYT + j8kazWyJUuufm6NVco1/35Zdp1UhHu8qTgXxrjo= + =zY9G + -----END PGP MESSAGE----- + % + +Strangely, the output doesn't say what PKA does (a PKA retrieval has a line +about fetching via HTTP), however, by checking my webserver logs, I can see it +retrieved it from there: + + %tail -200 /usr/local/apache/logs/prime.gushi.org.log | grep pubkey | tail -1 + prime.gushi.org 72.9.101.130 - - [28/Oct/2009:23:50:43 -0400] "GET /danm.pubkey.txt HTTP/1.1" 200 4337 "-" "-" + % + +As usual, test decryption, etc. You're done. + +## Further Steps + +* Figure out which of these are useful to you, and use them.* When someone + asks for your public key, tell them to run the above command instead of + mailing them your key or sending them a keyserver URL. + +* Consider using the pka-related verify-options. + +* Look into embracing DNSSEC. With a signed root, there's a good trust-path + vector here. Who knows, maybe some day GPG will be dnssec-aware so it will + give more credit to a secure DNS transaction. Without a signed root, there + are still ways to have those who care about security use it, through + services such as [ISC's DLV registry](http://dlv.isc.org). + +* On DNSSEC: At present, GPG cannot see the difference between an insecure + response (one from an unsigned zone) and a correctly validated one from a + signed zone. (In a signed zone, an unsigned or malformed will simply get a + SERVFAIL dns response). Look into sponsoring development of GPG to make it + as an application more aware of this. + +## A better way to generate records + +In reading over a lot of these commands, I've come across a few problems with +the tools involved. They either require you to assemble large records by +hand, or manipulate huge files. + +DNS has also come a long way since these tools were written, and RFCs have +solidified that have determined the "presentation format" (i.e. the "master +file format") of what CERT records should look like. + +On top of everything, the make-dns-cert tool is not built by default, and is +not present in most binary distributions (RPM's, deb packages, FreeBSD's +ports). + +Thus, I took it upon myself to rewrite make-dns-cert as a shell script. + +### Advantages + +* Extracts your key for you (takes a keyid as the argument). +* Formats all three record types for you, you can pipe it right into your zone + file. +* Takes email address as an argument, generates record label. +* No compiling needed. +* Should work with most systems. Requires openssl and sed, a few other + standard utilities. +* Generates base64-ified CERT records, split into easy, manageable pieces. +* Generates DNS-friendly comments, so repeating tasks are easy to reference. +* (Eventually) available as a tarball, or as a paste-and-go script. +* Arguments are in logical DNS record order `emailaddress keyid [url]`. +* Will generate an IPGP CERT record without a URI (this is legal per RFC4398). + +You can see sample output +[here](http://www.gushi.org/make-dns-cert/sample-output.txt), and you can view +the script itself +[here](http://www.gushi.org/make-dns-cert/make-dns-cert.sh.txt). Depending on +your MIME settings, you can probably get a download link if you go +[here](http://www.gushi.org/make-dns-cert/make-dns-cert.sh). If you see the +script rather than getting a download prompt, you can just save-as. + +README, Changelog, TODO coming soon. + +## Other notes + +I'm not 100 percent sure (mainly because I haven't tried), but with IPGP cert, +and PKA, I believe I could in theory point at a keyserver directly, for +example, specify a uri of +[http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xB0307039309C17C5](http://pgp.mit.edu:11371/pks/lookup?op=get&search=0xB0307039309C17C5). +I'm a bit dubious about the question marks and equals-signs, or if I might +have to uri-encode things. It's something to be tried. + +I'm trying to convince the GPG people that this would be much better adopted +if the make-dns-cert tool was built/included by default, or if its function +were included in gpg rather than a third-party tool. This is analagous as to +how dnssec-keygen is used to generate SSHFP DNS records. + +It doesn't do any actual cryptography, just some binary conversion, so in +theory it could be rewritten in pure-perl, so there's nothing to compile. + +I've made the argument to the GPG developers that if multiple CERT records are +available, all should be tried if one fails. So far, if multiple exist, only +the first received is parsed, and of course, DNS round-robins the answers by +default. + +It took me quite a lot of trial and error to realize that there's a difference +between "modern" RSA keys, like this: + + %gpg --list-keys --fingerprint gushi@prime.gushi.org + pub 2048R/CF45887D 2009-10-29 + Key fingerprint = FCB0 485E 050D DDFA 83C6 76E3 E722 3C05 CF45 887D + uid Gushi Test <gushi@prime.gushi.org> + sub 2048R/C9761244 2009-10-29 + +and ancient RSA keys like this pgp2.6.2 monster: + + %gpg --list-keys --fingerprint danm@prime.gushi.org + pub 1024R/309C17C5 1997-05-08 + Key fingerprint = 04 4B 1A 2E C4 62 95 73 73 A4 EA D0 08 A4 45 76 + uid Daniel P. Mahoney <danm@prime.gushi.org> + +Note the lack of a subkey there. Note the weird fingerprint. I have not been +able to get this key to properly export with gpg. If someone knows the Deep +Magic, let me know. + +## References + +### Blog posts and list threads + +While researching this I came across little more than a few blog posts, and a +few short discussions on the gpg-devel mailing list. + +* [A blog entry](http://www.df7cb.de/blog/2007/openpgp-dns.html) that seems to + have things mostly right. + +* [GPG Mailing List Discussion](http://lists.gnupg.org/pipermail/gnupg-users/2006-April/028314.html) + which seems to date towhen these features were first added. + +* [My own thread](http://www.mail-archive.com/gnupg-users@gnupg.org/msg12336.html) + on the gnupg-users mailing list that led upto this doc. + +* [A slideshow of a talk given on PKA](ftp://ftp.g10code.com/people/werner/talks/pka-intro.ps.gz) + (really the only doc I couldfind with regard to PKA). Note that this is a + postscript doc, for reasons I cannot fathom. + +### RFCs + +* [RFC 3597](http://www.faqs.org/rfcs/rfc3597.html) defines the odd format of + the records that make-dns-cert generates, if itconfuses you. + +* [RFC 2538](http://www.faqs.org/rfcs/rfc2538.html), which was superseded by + [RFC4398](http://www.faqs.org/rfcs/rfc4398.html), defines the format for a + CERT record. + +## Todo + +* At least one GPG enthusiast has suggested to me that any tools I write to + handle keys should simply be able to insert themusing nsupdate. I don't + disagree, but there's a complicated metric there as some of these require + manipulation of a site'smain zone, or at the very least, many subzones. In + doing this I'd also like to find out a bit about how to do nsupdate + withsig(0) and KEY records, which with the right policies would mean I could + do this without touching named.conf. That may be the subject of a whole + other howto. + +* (Done) I need to get the shell script cleaned up a bit more, and generate + proper docs, and start tracking it with version control. + +* I should probably get the gumption up to formally license all this stuff. + For right now, I declare it under the + [ISCLicense](http://en.wikipedia.org/wiki/ISC_license). + +* I'd like to track down the full list of supported URI types for PKA/IPGP + CERT records. There doesn't seem to be a defined standard for it. + +## Epilogue + +### About the author + +Dan Mahoney is a Systems Admin in the Bay Area, California. In his spare time +he enjoys thinking for those brief fleeting moments what he would do if he had +more free time. Keyid 624BB249, or email address danm@prime.gushi.org. + +### About this Document + +This document was written in [gnu nano](http://nano-editor.org), and HTML was +generated using [Markdown](http://daringfireball.net/projects/markdown). + +Markdown rocks. + +Originally published on my livejournal at +[http://gushi.livejournal.com/524199.html](http://gushi.livejournal.com/524199.html), +its main home is at +[http://www.gushi.org/make-dns-cert/HOWTO.html](http://www.gushi.org/make-dns-cert/HOWTO.html), +which is where later versions will be published. + +Free to use, comments to the above email address are welcome. diff --git a/docs/DETAILS b/docs/DETAILS new file mode 100644 index 0000000..d5c5cea --- /dev/null +++ b/docs/DETAILS @@ -0,0 +1,1225 @@ +# doc/DETAILS -*- org -*- +#+TITLE: GnuPG Details +# Globally disable superscripts and subscripts: +#+OPTIONS: ^:{} +# + +# Note: This file uses org-mode; it should be easy to read as plain +# text but be aware of some markup peculiarities: Verbatim code is +# enclosed in #+begin-example, #+end-example blocks or marked by a +# colon as the first non-white-space character, words bracketed with +# equal signs indicate a monospace font, and the usual /italics/, +# *bold*, and _underline_ conventions are recognized. + +This is the DETAILS file for GnuPG which specifies some internals and +parts of the external API for GPG and GPGSM. + +* Format of the colon listings + The format is a based on colon separated record, each recods starts + with a tag string and extends to the end of the line. Here is an + example: +#+begin_example +$ gpg --with-colons --list-keys \ + --with-fingerprint --with-fingerprint wk@gnupg.org +pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC: +fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013: +uid:f::::::::Werner Koch : +uid:f::::::::Werner Koch : +sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e: +fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1: +sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc: +fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4: +#+end_example + +The double =--with-fingerprint= prints the fingerprint for the subkeys +too. Old versions of gpg used a lighly different format and required +the use of the option =--fixed-list-mode= to conform to format +described here. + +** Description of the fields +*** Field 1 - Type of record + + - pub :: Public key + - crt :: X.509 certificate + - crs :: X.509 certificate and private key available + - sub :: Subkey (secondary key) + - sec :: Secret key + - ssb :: Secret subkey (secondary key) + - uid :: User id (only field 10 is used). + - uat :: User attribute (same as user id except for field 10). + - sig :: Signature + - rev :: Revocation signature + - fpr :: Fingerprint (fingerprint is in field 10) + - pkd :: Public key data [*] + - grp :: Keygrip + - rvk :: Revocation key + - tru :: Trust database information [*] + - spk :: Signature subpacket [*] + - cfg :: Configuration data [*] + + Records marked with an asterisk are described at [[*Special%20field%20formats][*Special fields]]. + +*** Field 2 - Validity + + This is a letter describing the computed validity of a key. + Currently this is a single letter, but be prepared that additional + information may follow in some future versions. Note that GnuPG < + 2.1 does not set this field for secret key listings. + + - o :: Unknown (this key is new to the system) + - i :: The key is invalid (e.g. due to a missing self-signature) + - d :: The key has been disabled + (deprecated - use the 'D' in field 12 instead) + - r :: The key has been revoked + - e :: The key has expired + - - :: Unknown validity (i.e. no value assigned) + - q :: Undefined validity. '-' and 'q' may safely be treated as + the same value for most purposes + - n :: The key is not valid + - m :: The key is marginal valid. + - f :: The key is fully valid + - u :: The key is ultimately valid. This often means that the + secret key is available, but any key may be marked as + ultimately valid. + - w :: The key has a well known private part. + - s :: The key has special validity. This means that it might be + self-signed and expected to be used in the STEED sytem. + + If the validity information is given for a UID or UAT record, it + describes the validity calculated based on this user ID. If given + for a key record it describes the validity taken from the best + rated user ID. + + For X.509 certificates a 'u' is used for a trusted root + certificate (i.e. for the trust anchor) and an 'f' for all other + valid certificates. + +*** Field 3 - Key length + + The length of key in bits. + +*** Field 4 - Public key algorithm + + The values here are those from the OpenPGP specs or if they are + greather than 255 the algorithm ids as used by Libgcrypt. + +*** Field 5 - KeyID + + This is the 64 bit keyid as specified by OpenPGP and the last 64 + bit of the SHA-1 fingerprint of an X.509 certifciate. + +*** Field 6 - Creation date + + The creation date of the key is given in UTC. For UID and UAT + records, this is used for the self-signature date. Note that the + date is usally printed in seconds since epoch, however, we are + migrating to an ISO 8601 format (e.g. "19660205T091500"). This is + currently only relevant for X.509. A simple way to detect the new + format is to scan for the 'T'. Note that old versions of gpg + without using the =--fixed-list-mode= option used a "yyyy-mm-tt" + format. + +*** Field 7 - Expiration date + + Key or UID/UAT expiration date or empty if it does not expire. + +*** Field 8 - Certificate S/N, UID hash, trust signature info + + Used for serial number in crt records. For UID and UAT records, + this is a hash of the user ID contents used to represent that + exact user ID. For trust signatures, this is the trust depth + seperated by the trust value by a space. + +*** Field 9 - Ownertrust + + This is only used on primary keys. This is a single letter, but + be prepared that additional information may follow in future + versions. For trust signatures with a regular expression, this is + the regular expression value, quoted as in field 10. + +*** Field 10 - User-ID + The value is quoted like a C string to avoid control characters + (the colon is quoted =\x3a=). For a "pub" record this field is + not used on --fixed-list-mode. A UAT record puts the attribute + subpacket count here, a space, and then the total attribute + subpacket size. In gpgsm the issuer name comes here. A FPR + record stores the fingerprint here. The fingerprint of a + revocation key is stored here. +*** Field 11 - Signature class + + Signature class as per RFC-4880. This is a 2 digit hexnumber + followed by either the letter 'x' for an exportable signature or + the letter 'l' for a local-only signature. The class byte of an + revocation key is also given here, 'x' and 'l' is used the same + way. This field if not used for X.509. + +*** Field 12 - Key capabilities + + The defined capabilities are: + + - e :: Encrypt + - s :: Sign + - c :: Certify + - a :: Authentication + - ? :: Unknown capability + + A key may have any combination of them in any order. In addition + to these letters, the primary key has uppercase versions of the + letters to denote the _usable_ capabilities of the entire key, and + a potential letter 'D' to indicate a disabled key. + +*** Field 13 - Issuer certificate fingerprint or other info + + Used in FPR records for S/MIME keys to store the fingerprint of + the issuer certificate. This is useful to build the certificate + path based on certificates stored in the local key database it is + only filled if the issuer certificate is available. The root has + been reached if this is the same string as the fingerprint. The + advantage of using this value is that it is guaranteed to have + been been build by the same lookup algorithm as gpgsm uses. + + For "uid" records this field lists the preferences in the same way + gpg's --edit-key menu does. + + For "sig" records, this is the fingerprint of the key that issued + the signature. Note that this is only filled in if the signature + verified correctly. Note also that for various technical reasons, + this fingerprint is only available if --no-sig-cache is used. + +*** Field 14 - Flag field + + Flag field used in the --edit menu output + +*** Field 15 - S/N of a token + + Used in sec/sbb to print the serial number of a token (internal + protect mode 1002) or a '#' if that key is a simple stub (internal + protect mode 1001) + +*** Field 16 - Hash algorithm + + For sig records, this is the used hash algorithm. For example: + 2 = SHA-1, 8 = SHA-256. + +** Special fields + +*** PKD - Public key data + + If field 1 has the tag "pkd", a listing looks like this: +#+begin_example +pkd:0:1024:B665B1435F4C2 .... FF26ABB: + ! ! !-- the value + ! !------ for information number of bits in the value + !--------- index (eg. DSA goes from 0 to 3: p,q,g,y) +#+end_example + +*** TRU - Trust database information + Example for a "tru" trust base record: +#+begin_example + tru:o:0:1166697654:1:3:1:5 +#+end_example + + - Field 2 :: Reason for staleness of trust. If this field is + empty, then the trustdb is not stale. This field may + have multiple flags in it: + + - o :: Trustdb is old + - t :: Trustdb was built with a different trust model + than the one we are using now. + + - Field 3 :: Trust model + + - 0 :: Classic trust model, as used in PGP 2.x. + - 1 :: PGP trust model, as used in PGP 6 and later. + This is the same as the classic trust model, + except for the addition of trust signatures. + + GnuPG before version 1.4 used the classic trust model + by default. GnuPG 1.4 and later uses the PGP trust + model by default. + + - Field 4 :: Date trustdb was created in seconds since Epoch. + - Field 5 :: Date trustdb will expire in seconds since Epoch. + - Field 6 :: Number of marginally trusted users to introduce a new + key signer (gpg's option --marginals-needed). + - Field 7 :: Number of completely trusted users to introduce a new + key signer. (gpg's option --completes-needed) + + - Field 8 :: Maximum depth of a certification chain. (gpg's option + --max-cert-depth) + +*** SPK - Signature subpacket records + + - Field 2 :: Subpacket number as per RFC-4880 and later. + - Field 3 :: Flags in hex. Currently the only two bits assigned + are 1, to indicate that the subpacket came from the + hashed part of the signature, and 2, to indicate the + subpacket was marked critical. + - Field 4 :: Length of the subpacket. Note that this is the + length of the subpacket, and not the length of field + 5 below. Due to the need for %-encoding, the length + of field 5 may be up to 3x this value. + - Field 5 :: The subpacket data. Printable ASCII is shown as + ASCII, but other values are rendered as %XX where XX + is the hex value for the byte. + +*** CFG - Configuration data + + --list-config outputs information about the GnuPG configuration + for the benefit of frontends or other programs that call GnuPG. + There are several list-config items, all colon delimited like the + rest of the --with-colons output. The first field is always "cfg" + to indicate configuration information. The second field is one of + (with examples): + + - version :: The third field contains the version of GnuPG. + + : cfg:version:1.3.5 + + - pubkey :: The third field contains the public key algorithms + this version of GnuPG supports, separated by + semicolons. The algorithm numbers are as specified in + RFC-4880. Note that in contrast to the --status-fd + interface these are _not_ the Libgcrypt identifiers. + + : cfg:pubkey:1;2;3;16;17 + + - cipher :: The third field contains the symmetric ciphers this + version of GnuPG supports, separated by semicolons. + The cipher numbers are as specified in RFC-4880. + + : cfg:cipher:2;3;4;7;8;9;10 + + - digest :: The third field contains the digest (hash) algorithms + this version of GnuPG supports, separated by + semicolons. The digest numbers are as specified in + RFC-4880. + + : cfg:digest:1;2;3;8;9;10 + + - compress :: The third field contains the compression algorithms + this version of GnuPG supports, separated by + semicolons. The algorithm numbers are as specified + in RFC-4880. + + : cfg:compress:0;1;2;3 + + - group :: The third field contains the name of the group, and the + fourth field contains the values that the group expands + to, separated by semicolons. + + For example, a group of: + : group mynames = paige 0x12345678 joe patti + would result in: + : cfg:group:mynames:patti;joe;0x12345678;paige + + +* Format of the --status-fd output + + Every line is prefixed with "[GNUPG:] ", followed by a keyword with + the type of the status line and some arguments depending on the type + (maybe none); an application should always be prepared to see more + arguments in future versions. + +** General status codes +*** NEWSIG + May be issued right before a signature verification starts. This + is useful to define a context for parsing ERROR status messages. + No arguments are currently defined. + +*** GOODSIG + The signature with the keyid is good. For each signature only one + of the codes GOODSIG, BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or + ERRSIG will be emitted. In the past they were used as a marker + for a new signature; new code should use the NEWSIG status + instead. The username is the primary one encoded in UTF-8 and %XX + escaped. The fingerprint may be used instead of the long keyid if + it is available. This is the case with CMS and might eventually + also be available for OpenPGP. + +*** EXPSIG + The signature with the keyid is good, but the signature is + expired. The username is the primary one encoded in UTF-8 and %XX + escaped. The fingerprint may be used instead of the long keyid if + it is available. This is the case with CMS and might eventually + also be available for OpenPGP. + +*** EXPKEYSIG + The signature with the keyid is good, but the signature was made + by an expired key. The username is the primary one encoded in + UTF-8 and %XX escaped. The fingerprint may be used instead of the + long keyid if it is available. This is the case with CMS and + might eventually also be available for OpenPGP. + +*** REVKEYSIG + The signature with the keyid is good, but the signature was made + by a revoked key. The username is the primary one encoded in UTF-8 + and %XX escaped. The fingerprint may be used instead of the long + keyid if it is available. This is the case with CMS and might + eventually also beñ available for OpenPGP. + +*** BADSIG + The signature with the keyid has not been verified okay. The + username is the primary one encoded in UTF-8 and %XX escaped. The + fingerprint may be used instead of the long keyid if it is + available. This is the case with CMS and might eventually also be + available for OpenPGP. + +*** ERRSIG + It was not possible to check the signature. This may be caused by + a missing public key or an unsupported algorithm. A RC of 4 + indicates unknown algorithm, a 9 indicates a missing public + key. The other fields give more information about this signature. + sig_class is a 2 byte hex-value. The fingerprint may be used + instead of the keyid if it is available. This is the case with + gpgsm and might eventually also be available for OpenPGP. + + Note, that TIME may either be the number of seconds since Epoch or + the letter 'T'. + an ISO 8601 string. The latter can be detected by the presence of + +*** VALIDSIG + + The args are: + + - + - + - + - + - + - + - + - + - + - [ ] + + This status indicates that the signature is good. This is the same + as GOODSIG but has the fingerprint as the argument. Both status + lines are emitted for a good signature. All arguments here are on + one long line. sig-timestamp is the signature creation time in + seconds after the epoch. expire-timestamp is the signature + expiration time in seconds after the epoch (zero means "does not + expire"). sig-version, pubkey-algo, hash-algo, and sig-class (a + 2-byte hex value) are all straight from the signature packet. + PRIMARY-KEY-FPR is the fingerprint of the primary key or identical + to the first argument. This is useful to get back to the primary + key without running gpg again for this purpose. + + The primary-key-fpr parameter is used for OpenPGP and not + class is not defined for CMS and currently set to 0 and 00. + available for CMS signatures. The sig-version as well as the sig + + Note, that *-TIMESTAMP may either be a number of seconds since + Epoch or an ISO 8601 string which can be detected by the presence + of the letter 'T'. + +*** SIG_ID

+ This is emitted only for signatures of class 0 or 1 which have + been verified okay. The string is a signature id and may be used + in applications to detect replay attacks of signed messages. Note + that only DLP algorithms give unique ids - others may yield + duplicated ones when they have been created in the same second. + + Note, that SIG-TIMESTAMP may either be a number of seconds since + Epoch or an ISO 8601 string which can be detected by the presence + of the letter 'T'. + +*** ENC_TO + The message is encrypted to this LONG_KEYID. KEYTYPE is the + numerical value of the public key algorithm or 0 if it is not + known, KEYLENGTH is the length of the key or 0 if it is not known + (which is currently always the case). Gpg prints this line + always; Gpgsm only if it knows the certificate. + +*** BEGIN_DECRYPTION + Mark the start of the actual decryption process. This is also + emitted when in --list-only mode. +*** END_DECRYPTION + Mark the end of the actual decryption process. This are also + emitted when in --list-only mode. +*** DECRYPTION_INFO + Print information about the symmetric encryption algorithm and the + MDC method. This will be emitted even if the decryption fails. + +*** DECRYPTION_FAILED + The symmetric decryption failed - one reason could be a wrong + passphrase for a symmetrical encrypted message. + +*** DECRYPTION_OKAY + The decryption process succeeded. This means, that either the + correct secret key has been used or the correct passphrase for a + conventional encrypted message was given. The program itself may + return an errorcode because it may not be possible to verify a + signature for some reasons. + +*** SESSION_KEY : + The session key used to decrypt the message. This message will + only be emitted when the special option --show-session-key is + used. The format is suitable to be passed to the option + --override-session-key + +*** BEGIN_ENCRYPTION + Mark the start of the actual encryption process. + +*** END_ENCRYPTION + Mark the end of the actual encryption process. + +*** FILE_START + Start processing a file . indicates the performed + operation: + - 1 :: verify + - 2 :: encrypt + - 3 :: decrypt + +*** FILE_DONE + Marks the end of a file processing which has been started + by FILE_START. + +*** BEGIN_SIGNING + Mark the start of the actual signing process. This may be used as + an indication that all requested secret keys are ready for use. + +*** ALREADY_SIGNED + Warning: This is experimental and might be removed at any time. + +*** SIG_CREATED + A signature has been created using these parameters. + Values for type are: + - D :: detached + - C :: cleartext + - S :: standard + (only the first character should be checked) + + are 2 hex digits with the OpenPGP signature class. + + Note, that TIMESTAMP may either be a number of seconds since Epoch + or an ISO 8601 string which can be detected by the presence of the + letter 'T'. + +*** NOTATION_ + There are actually two related status codes to convey notation + data: + + - NOTATION_NAME + - NOTATION_DATA + + and are %XX escaped; the data may be split among + several NOTATION_DATA lines. + +*** POLICY_URL + Note that URL in is %XX escaped. + +*** PLAINTEXT + This indicates the format of the plaintext that is about to be + written. The format is a 1 byte hex code that shows the format of + the plaintext: 62 ('b') is binary data, 74 ('t') is text data with + no character set specified, and 75 ('u') is text data encoded in + the UTF-8 character set. The timestamp is in seconds since the + epoch. If a filename is available it gets printed as the third + argument, percent-escaped as usual. + +*** PLAINTEXT_LENGTH + This indicates the length of the plaintext that is about to be + written. Note that if the plaintext packet has partial length + encoding it is not possible to know the length ahead of time. In + that case, this status tag does not appear. + +*** ATTRIBUTE + The list or argemnts are: + - + - + - + - + - + - + - + - + + This is one long line issued for each attribute subpacket when an + attribute packet is seen during key listing. is the + fingerprint of the key. is the length of the attribute + subpacket. is the attribute type (e.g. 1 for an image). + and indicate that this is the N-th indexed + subpacket of count total subpackets in this attribute packet. + and are from the self-signature on the + attribute packet. If the attribute packet does not have a valid + self-signature, then the timestamp is 0. are a bitwise OR + of: + - 0x01 :: this attribute packet is a primary uid + - 0x02 :: this attribute packet is revoked + - 0x04 :: this attribute packet is expired + +*** SIG_SUBPACKET + This indicates that a signature subpacket was seen. The format is + the same as the "spk" record above. + +** Key related +*** INV_RECP, INV_SGNR + The two similar status codes: + + - INV_RECP + - INV_SGNR + + are issued for each unusable recipient/sender. The reasons codes + currently in use are: + + - 0 :: No specific reason given + - 1 :: Not Found + - 2 :: Ambigious specification + - 3 :: Wrong key usage + - 4 :: Key revoked + - 5 :: Key expired + - 6 :: No CRL known + - 7 :: CRL too old + - 8 :: Policy mismatch + - 9 :: Not a secret key + - 10 :: Key not trusted + - 11 :: Missing certificate + - 12 :: Missing issuer certificate + + Note that for historical reasons the INV_RECP status is also used + for gpgsm's SIGNER command where it relates to signer's of course. + Newer GnuPG versions are using INV_SGNR; applications should + ignore the INV_RECP during the sender's command processing once + they have seen an INV_SGNR. Different codes are used so that they + can be distinguish while doing an encrypt+sign operation. +*** NO_RECP + Issued if no recipients are usable. + +*** NO_SGNR + Issued if no senders are usable. + +*** KEYEXPIRED + The key has expired. expire-timestamp is the expiration time in + seconds since Epoch. This status line is not very useful because + it will also be emitted for expired subkeys even if this subkey is + not used. To check whether a key used to sign a message has + expired, the EXPKEYSIG status line is to be used. + + Note, that the TIMESTAMP may either be a number of seconds since + Epoch or an ISO 8601 string which can be detected by the presence + of the letter 'T'. + +*** KEYREVOKED + The used key has been revoked by its owner. No arguments yet. + +*** NO_PUBKEY + The public key is not available + +*** NO_SECKEY + The secret key is not available + +*** KEY_CREATED [] + A key has been created. Values for are: + - B :: primary and subkey + - P :: primary + - S :: subkey + The fingerprint is one of the primary key for type B and P and the + one of the subkey for S. Handle is an arbitrary non-whitespace + string used to match key parameters from batch key creation run. + +*** KEY_NOT_CREATED [] + The key from batch run has not been created due to errors. + +*** TRUST_ + These are several similar status codes: + + - TRUST_UNDEFINED + - TRUST_NEVER + - TRUST_MARGINAL [0 []] + - TRUST_FULLY [0 []] + - TRUST_ULTIMATE [0 []] + + For good signatures one of these status lines are emitted to + indicate the validity of the key used to create the signature. + The error token values are currently only emitted by gpgsm. + + VALIDATION_MODEL describes the algorithm used to check the + validity of the key. The defaults are the standard Web of Trust + model for gpg and the the standard X.509 model for gpgsm. The + defined values are + + - pgp :: The standard PGP WoT. + - shell :: The standard X.509 model. + - chain :: The chain model. + - steed :: The STEED model. + + Note that the term =TRUST_= in the status names is used for + historic reasons; we now speak of validity. + +*** PKA_TRUST_ + This is is one: + + - PKA_TRUST_GOOD + - PKA_TRUST_BAD + + Depending on the outcome of the PKA check one of the above status + codes is emitted in addition to a =TRUST_*= status. + +** Remote control +*** GET_BOOL, GET_LINE, GET_HIDDEN, GOT_IT + + These status line are used with --command-fd for interactive + control of the process. + +*** USERID_HINT + Give a hint about the user ID for a certain keyID. + +*** NEED_PASSPHRASE + Issued whenever a passphrase is needed. KEYTYPE is the numerical + value of the public key algorithm or 0 if this is not applicable, + KEYLENGTH is the length of the key or 0 if it is not known (this + is currently always the case). + +*** NEED_PASSPHRASE_SYM + Issued whenever a passphrase for symmetric encryption is needed. + +*** NEED_PASSPHRASE_PIN [] + Issued whenever a PIN is requested to unlock a card. + +*** MISSING_PASSPHRASE + No passphrase was supplied. An application which encounters this + message may want to stop parsing immediately because the next + message will probably be a BAD_PASSPHRASE. However, if the + application is a wrapper around the key edit menu functionality it + might not make sense to stop parsing but simply ignoring the + following BAD_PASSPHRASE. + +*** BAD_PASSPHRASE + The supplied passphrase was wrong or not given. In the latter + case you may have seen a MISSING_PASSPHRASE. + +*** GOOD_PASSPHRASE + The supplied passphrase was good and the secret key material + is therefore usable. + +** Import/Export +*** IMPORT_CHECK + This status is emitted in interactive mode right before + the "import.okay" prompt. + +*** IMPORTED + The keyid and name of the signature just imported + +*** IMPORT_OK [] + The key with the primary key's FINGERPRINT has been imported. + REASON flags are: + + - 0 :: Not actually changed + - 1 :: Entirely new key. + - 2 :: New user IDs + - 4 :: New signatures + - 8 :: New subkeys + - 16 :: Contains private key. + + The flags may be ORed. + +*** IMPORT_PROBLEM [] + Issued for each import failure. Reason codes are: + + - 0 :: No specific reason given. + - 1 :: Invalid Certificate. + - 2 :: Issuer Certificate missing. + - 3 :: Certificate Chain too long. + - 4 :: Error storing certificate. + +*** IMPORT_RES + Final statistics on import process (this is one long line). The + args are a list of unsigned numbers separated by white space: + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + +** Smartcard related +*** CARDCTRL [] + This is used to control smartcard operations. Defined values for + WHAT are: + + - 1 :: Request insertion of a card. Serialnumber may be given + to request a specific card. Used by gpg 1.4 w/o + scdaemon + - 2 :: Request removal of a card. Used by gpg 1.4 w/o scdaemon. + - 3 :: Card with serialnumber detected + - 4 :: No card available + - 5 :: No card reader available + - 6 :: No card support available + +*** SC_OP_FAILURE [] + An operation on a smartcard definitely failed. Currently there is + no indication of the actual error code, but application should be + prepared to later accept more arguments. Defined values for + are: + + - 0 :: unspecified error (identically to a missing CODE) + - 1 :: canceled + - 2 :: bad PIN + +*** SC_OP_SUCCESS + A smart card operaion succeeded. This status is only printed for + certain operation and is mostly useful to check whether a PIN + change really worked. + +** Miscellaneous status codes +*** NODATA + No data has been found. Codes for WHAT are: + + - 1 :: No armored data. + - 2 :: Expected a packet but did not found one. + - 3 :: Invalid packet found, this may indicate a non OpenPGP + message. + - 4 :: Signature expected but not found + + You may see more than one of these status lines. + +*** UNEXPECTED + Unexpected data has been encountered. Codes for WHAT are: + - 0 :: Not further specified + +*** TRUNCATED + The output was truncated to MAXNO items. This status code is + issued for certain external requests. + +*** ERROR [] + This is a generic error status message, it might be followed by + error location specific data. and + should not contain spaces. The error code is a either a string + commencing with a letter or such a string prefixed with a + numerical error code and an underscore; e.g.: "151011327_EOF". + +*** SUCCESS [] + Postive confirimation that an operation succeeded. is + optional but if given should not contain spaces. Used only with a + few commands. + +*** BADARMOR + The ASCII armor is corrupted. No arguments yet. + +*** DELETE_PROBLEM + Deleting a key failed. Reason codes are: + - 1 :: No such key + - 2 :: Must delete secret key first + - 3 :: Ambigious specification + +*** PROGRESS + Used by the primegen and Public key functions to indicate + progress. is the character displayed with no --status-fd + enabled, with the linefeed replaced by an 'X'. is the + current amount done and is amount to be done; a of + 0 indicates that the total amount is not known. The condition + : TOTAL && CUR == TOTAL + may be used to detect the end of an operation. + + Well known values for WHAT are: + + - pk_dsa :: DSA key generation + - pk_elg :: Elgamal key generation + - primegen :: Prime generation + - need_entropy :: Waiting for new entropy in the RNG + - tick :: Generic tick without any special meaning - useful + for letting clients know that the server is still + working. + - starting_agent :: A gpg-agent was started because it is not + running as a daemon. + - learncard :: Send by the agent and gpgsm while learing + the data of a smartcard. + - card_busy :: A smartcard is still working + +*** BACKUP_KEY_CREATED + A backup of a key identified by has been writte to + the file ; is percent-escaped. + +*** MOUNTPOINT + is a percent-plus escaped filename describing the + mountpoint for the current operation (e.g. used by "g13 --mount"). + This may either be the specified mountpoint or one randomly + choosen by g13. + +*** PINENTRY_LAUNCHED + This status line is emitted by gpg to notify a client that a + Pinentry has been launched. is the PID of the Pinentry. It + may be used to display a hint to the user but can't be used to + synchronize with Pinentry. Note that there is also an Assuan + inquiry line with the same name used internally or, if enabled, + send to the client instead of this status line. Such an inquiry + may be used to sync with Pinentry + +** Obsolete status codes +*** SIGEXPIRED + Removed on 2011-02-04. This is deprecated in favor of KEYEXPIRED. +*** RSA_OR_IDEA + Obsolete. This status message used to be emitted for requests to + use the IDEA or RSA algorithms. It has been dropped from GnuPG + 2.1 after the respective patents expired. +*** SHM_INFO, SHM_GET, SHM_GET_BOOL, SHM_GET_HIDDEN + These were used for the ancient shared memory based co-processing. +*** BEGIN_STREAM, END_STREAM + Used to issued by the experimental pipemode. + + +* Format of the --attribute-fd output + + When --attribute-fd is set, during key listings (--list-keys, + --list-secret-keys) GnuPG dumps each attribute packet to the file + descriptor specified. --attribute-fd is intended for use with + --status-fd as part of the required information is carried on the + ATTRIBUTE status tag (see above). + + The contents of the attribute data is specified by RFC 4880. For + convenience, here is the Photo ID format, as it is currently the + only attribute defined: + + - Byte 0-1 :: The length of the image header. Due to a historical + accident (i.e. oops!) back in the NAI PGP days, this + is a little-endian number. Currently 16 (0x10 0x00). + + - Byte 2 :: The image header version. Currently 0x01. + + - Byte 3 :: Encoding format. 0x01 == JPEG. + + - Byte 4-15 :: Reserved, and currently unused. + + All other data after this header is raw image (JPEG) data. + + +* Unattended key generation + + Please see the GnuPG manual for a description. + + +* Layout of the TrustDB + + The TrustDB is built from fixed length records, where the first byte + describes the record type. All numeric values are stored in network + byte order. The length of each record is 40 bytes. The first record + of the DB is always of type 1 and this is the only record of this + type. + + FIXME: The layout changed, document it here. +#+begin_example + Record type 0: + -------------- + Unused record, can be reused for any purpose. + + Record type 1: + -------------- + Version information for this TrustDB. This is always the first + record of the DB and the only one with type 1. + 1 byte value 1 + 3 bytes 'gpg' magic value + 1 byte Version of the TrustDB (2) + 1 byte marginals needed + 1 byte completes needed + 1 byte max_cert_depth + The three items are used to check whether the cached + validity value from the dir record can be used. + 1 u32 locked flags [not used] + 1 u32 timestamp of trustdb creation + 1 u32 timestamp of last modification which may affect the validity + of keys in the trustdb. This value is checked against the + validity timestamp in the dir records. + 1 u32 timestamp of last validation [currently not used] + (Used to keep track of the time, when this TrustDB was checked + against the pubring) + 1 u32 record number of keyhashtable [currently not used] + 1 u32 first free record + 1 u32 record number of shadow directory hash table [currently not used] + It does not make sense to combine this table with the key table + because the keyid is not in every case a part of the fingerprint. + 1 u32 record number of the trusthashtbale + + + Record type 2: (directory record) + -------------- + Informations about a public key certificate. + These are static values which are never changed without user interaction. + + 1 byte value 2 + 1 byte reserved + 1 u32 LID . (This is simply the record number of this record.) + 1 u32 List of key-records (the first one is the primary key) + 1 u32 List of uid-records + 1 u32 cache record + 1 byte ownertrust + 1 byte dirflag + 1 byte maximum validity of all the user ids + 1 u32 time of last validity check. + 1 u32 Must check when this time has been reached. + (0 = no check required) + + + Record type 3: (key record) + -------------- + Informations about a primary public key. + (This is mainly used to lookup a trust record) + + 1 byte value 3 + 1 byte reserved + 1 u32 LID + 1 u32 next - next key record + 7 bytes reserved + 1 byte keyflags + 1 byte pubkey algorithm + 1 byte length of the fingerprint (in bytes) + 20 bytes fingerprint of the public key + (This is the value we use to identify a key) + + Record type 4: (uid record) + -------------- + Informations about a userid + We do not store the userid but the hash value of the userid because that + is sufficient. + + 1 byte value 4 + 1 byte reserved + 1 u32 LID points to the directory record. + 1 u32 next next userid + 1 u32 pointer to preference record + 1 u32 siglist list of valid signatures + 1 byte uidflags + 1 byte validity of the key calculated over this user id + 20 bytes ripemd160 hash of the username. + + + Record type 5: (pref record) + -------------- + This record type is not anymore used. + + 1 byte value 5 + 1 byte reserved + 1 u32 LID; points to the directory record (and not to the uid record!). + (or 0 for standard preference record) + 1 u32 next + 30 byte preference data + + Record type 6 (sigrec) + ------------- + Used to keep track of key signatures. Self-signatures are not + stored. If a public key is not in the DB, the signature points to + a shadow dir record, which in turn has a list of records which + might be interested in this key (and the signature record here + is one). + + 1 byte value 6 + 1 byte reserved + 1 u32 LID points back to the dir record + 1 u32 next next sigrec of this uid or 0 to indicate the + last sigrec. + 6 times + 1 u32 Local_id of signatures dir or shadow dir record + 1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real + directory record for this) + 1 = valid is set (but may be revoked) + + + + Record type 8: (shadow directory record) + -------------- + This record is used to reserve a LID for a public key. We + need this to create the sig records of other keys, even if we + do not yet have the public key of the signature. + This record (the record number to be more precise) will be reused + as the dir record when we import the real public key. + + 1 byte value 8 + 1 byte reserved + 1 u32 LID (This is simply the record number of this record.) + 2 u32 keyid + 1 byte pubkey algorithm + 3 byte reserved + 1 u32 hintlist A list of records which have references to + this key. This is used for fast access to + signature records which are not yet checked. + Note, that this is only a hint and the actual records + may not anymore hold signature records for that key + but that the code cares about this. + 18 byte reserved + + + + Record Type 10 (hash table) + -------------- + Due to the fact that we use fingerprints to lookup keys, we can + implement quick access by some simple hash methods, and avoid + the overhead of gdbm. A property of fingerprints is that they can be + used directly as hash values. (They can be considered as strong + random numbers.) + What we use is a dynamic multilevel architecture, which combines + hashtables, record lists, and linked lists. + + This record is a hashtable of 256 entries; a special property + is that all these records are stored consecutively to make one + big table. The hash value is simple the 1st, 2nd, ... byte of + the fingerprint (depending on the indirection level). + + When used to hash shadow directory records, a different table is used + and indexed by the keyid. + + 1 byte value 10 + 1 byte reserved + n u32 recnum; n depends on the record length: + n = (reclen-2)/4 which yields 9 for the current record length + of 40 bytes. + + the total number of such record which makes up the table is: + m = (256+n-1) / n + which is 29 for a record length of 40. + + To look up a key we use the first byte of the fingerprint to get + the recnum from this hashtable and look up the addressed record: + - If this record is another hashtable, we use 2nd byte + to index this hash table and so on. + - if this record is a hashlist, we walk all entries + until we found one a matching one. + - if this record is a key record, we compare the + fingerprint and to decide whether it is the requested key; + + + Record type 11 (hash list) + -------------- + see hash table for an explanation. + This is also used for other purposes. + + 1 byte value 11 + 1 byte reserved + 1 u32 next next hash list record + n times n = (reclen-5)/5 + 1 u32 recnum + + For the current record length of 40, n is 7 + + + + Record type 254 (free record) + --------------- + All these records form a linked list of unused records. + 1 byte value 254 + 1 byte reserved (0) + 1 u32 next_free +#+end_example + + +* GNU extensions to the S2K algorithm + + S2K mode 101 is used to identify these extensions. + After the hash algorithm the 3 bytes "GNU" are used to make + clear that these are extensions for GNU, the next bytes gives the + GNU protection mode - 1000. Defined modes are: + - 1001 :: Do not store the secret part at all. + - 1002 :: A stub to access smartcards (not used in 1.2.x) + +* Keyserver helper message format + + The keyserver may be contacted by a Unix Domain socket or via TCP. + + The format of a request is: +#+begin_example + command-tag + "Content-length:" digits + CRLF +#+end_example + + Where command-tag is + +#+begin_example + NOOP + GET + PUT + DELETE +#+end_example + +The format of a response is: + +#+begin_example + "GNUPG/1.0" status-code status-text + "Content-length:" digits + CRLF +#+end_example +followed by bytes of data + +Status codes are: + + - 1xx :: Informational - Request received, continuing process + + - 2xx :: Success - The action was successfully received, understood, + and accepted + + - 4xx :: Client Error - The request contains bad syntax or cannot be + fulfilled + + - 5xx :: Server Error - The server failed to fulfill an apparently + valid request + + +* Object identifiers + + OIDs below the GnuPG arc: + +#+begin_example + 1.3.6.1.4.1.11591.2 GnuPG + 1.3.6.1.4.1.11591.2.1 notation + 1.3.6.1.4.1.11591.2.1.1 pkaAddress + 1.3.6.1.4.1.11591.2.2 X.509 extensions + 1.3.6.1.4.1.11591.2.2.1 standaloneCertificate + 1.3.6.1.4.1.11591.2.2.2 wellKnownPrivateKey + 1.3.6.1.4.1.11591.2.12242973 invalid encoded OID +#+end_example + + + +* Miscellaneous notes + +** v3 fingerprints + For packet version 3 we calculate the keyids this way: + - RSA :: Low 64 bits of n + - ELGAMAL :: Build a v3 pubkey packet (with CTB 0x99) and + calculate a RMD160 hash value from it. This is used + as the fingerprint and the low 64 bits are the keyid. + +** Simplified revocation certificates + Revocation certificates consist only of the signature packet; + "--import" knows how to handle this. The rationale behind it is to + keep them small. + +** Documentation on HKP (the http keyserver protocol): + + A minimalistic HTTP server on port 11371 recognizes a GET for + /pks/lookup. The standard http URL encoded query parameters are + this (always key=value): + + - op=index (like pgp -kv), op=vindex (like pgp -kvv) and op=get (like + pgp -kxa) + + - search=. This is a list of words that must occur in the key. + The words are delimited with space, points, @ and so on. The delimiters + are not searched for and the order of the words doesn't matter (but see + next option). + + - exact=on. This switch tells the hkp server to only report exact matching + keys back. In this case the order and the "delimiters" are important. + + - fingerprint=on. Also reports the fingerprints when used with 'index' or + 'vindex' + + The keyserver also recognizes http-POSTs to /pks/add. Use this to upload + keys. + + + A better way to do this would be a request like: + + /pks/lookup/?op= + + This can be implemented using Hurd's translator mechanism. + However, I think the whole key server stuff has to be re-thought; + I have some ideas and probably create a white paper. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..2d43a93 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -E -n +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-gnupg.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-gnupg.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/python-gnupg" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/python-gnupg" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/NOTES-python-gnupg-3.1-audit.html b/docs/NOTES-python-gnupg-3.1-audit.html new file mode 100644 index 0000000..fbd6e0d --- /dev/null +++ b/docs/NOTES-python-gnupg-3.1-audit.html @@ -0,0 +1,946 @@ + + + + +python-gnupg audit + + + + + + + + + + + + + + + + + + +python-gnupg audit + + 2013-02-01 Fri + + + +Table of Contents + + +1 gnugp.__main_₍₎ + +1.1 comments +1.2 def _copy_data(instream, outstream) + +1.2.1 L79: +1.2.2 L78: +1.2.3 L88: + + +1.3 def _threaded_copy_data(instream, outstream): + +1.3.1 L99: + + +1.4 def _write_passphrase(stream, passphrase, encoding): + +1.4.1 L110: + + + +2 class Verify(object) +3 class ImportResult(object) +4 class ListKeys(list): +5 class Crypt(Verify): + +5.1 def __init__{(self, gpg)} + +5.1.1 L338 + + + +6 class GenKey(object) +7 class DeleteResult(object) +8 class Sign(object) +9 class GPG(object) + + + +9.1 L474: + + +9.1 def __init__{(self, gpgbinary='gpg', gnupghome=None, verbose=False, use_agent=False, keyring=None)} + +9.1.1 L494-495: + + +9.2 def _open_subprocess(self, args, passphrase=False) + +9.2.1 L515: + + +9.3 def _collect_output(self, process, result, writer=None, stdin=None) +9.4 def _handle_io(self, args, file, result, passphrase=None, binary=False) + +9.4.1 L601: + + +9.5 def sign(self, message, **kwargs) + +9.5.1 L617-619: + + +9.6 def sign_file(self, file, keyid=None, passphrase=None, clearsign=True, detach=False, binary=False) + +9.6.1 L632-635: +9.6.2 L626-641: + + +9.7 def verify(self, data): + +9.7.1 L668-670: + + +9.8 def verify_file(self, file, data_filename=None) + +9.8.1 L683: +9.8.2 L684: +9.8.3 L690: + + +9.9 def import_keys(self, key_data) + +9.9.1 L749: + + +9.10 def recieve_keys(self, keyserver, *keyids) + +9.10.1 L770: + + +9.11 def export_keys(self, keyids, secret=False) + +9.11.1 L795-796: + + +9.12 def list_keys(self, secret=False) + +9.12.1 L827: + + +9.13 def gen_key(self, input) + +9.13.1 L864: + + +9.14 def gen_key_input(self, **kwargs) + +9.14.1 L981-983: + + +9.15 def encrypt_file(self, file, recipiencts, sign=None, …) + +9.15.1 L939: + + +9.16 def encrypt(self, data, recipients, **kwargs): + +9.16.1 L997: + + +9.17 def decrypt(self, message **kwargs): + +9.17.1 L1003: + + +9.18 def decrypt_file(self, file, always_trust=False, passphrase=None, output=None) + +9.18.1 L1013: + + + +10 POC + + + + + +1 gnugp.__main_₍₎ + + + + + + +1.1 comments + + +L58 NullHandler?? see self._write_passphrase +L61 there nifty check for p3k + + + + + +1.2 def _copy_data(instream, outstream) cleanup + + + copies data from one stream to another, 1024 bytes at a time. + + + + +1.2.1 L79: bad_logic + + + instream is apparently a file descriptor, but is not checked nor + encased in a try/except block. + + + + + + +1.2.2 L78: hanging_fd bad_logic + + + while True: loop, should be + +with open(instream) as instrm: + + + + + + + +1.2.3 L88: bad_exception_handling + + ++except: + + + should catch an IOError, or whatever specific error is raised for broken + pipes. + + + + + + +1.3 def _threaded_copy_data(instream, outstream): + + + + + + +1.3.1 L99: + + + this just wraps self._copy_data in a thread + + + + + + +1.4 def _write_passphrase(stream, passphrase, encoding): vuln cleanup + + + + + + +1.4.1 L110: writes_passphrase_to_disk + + + logger writes passphrase into debug log. this should be patched. + + + + + + + +2 class Verify(object) + + + basic parsing class, no errors found + + + + + +3 class ImportResult(object) + + + basic parsing class, no errors found + + + + + +4 class ListKeys(list): + + + basic parsing class, no errors found + + + + + +5 class Crypt(Verify): + + + basic parsing class, no errors found + + + + +5.1 def __init__{(self, gpg)} cleanup + + + + + + +5.1.1 L338 mro_conflict + + + + + + +Verify.__init__(self,gpg) + + + + + should be changed to: + + + + +super(Verify, self).__init__(gpg) + + + + + + + + + +6 class GenKey(object) + + + basic parsing class, no errors found + + + + + +7 class DeleteResult(object) + + + basic parsing class, no errors found + + + + + +8 class Sign(object) + + + basic parsing class, no errors found + + + + + +9 class GPG(object) exploitable + + + + + + +9.1 L474: cleanup + + ++cls.__doc__ + + + should go directly underneath class signature + + + + + +9.1 def __init__{(self, gpgbinary='gpg', gnupghome=None, verbose=False, use_agent=False, keyring=None)} bug + + + + + + +9.1.1 L494-495: type_error + + + + + + +if gnupghome and not os.path.isdir(self.gnupghome): + os.makedirs(self.gnupghome,0x1C0) + + + + +In [20]: os.makedirs? +Type: function +String Form:<function makedirs at 0x7f8ddeb6cc08> +File: /usr/lib/python2.7/os.py +Definition: os.makedirs(name, mode=511) +Docstring: +makedirs(path [, mode=0777]) +Super-mkdir; create a leaf directory and all intermediate ones. +Works like mkdir, except that any intermediate path segment (not +just the rightmost) will be created if it does not exist. This is +recursive. + +setting mode=0x1c0 is equivalent to mode=hex(0700), which +may cause bugs on some systems, see +http://ubuntuforums.org/showthread.php?t=2044879 + +this could be do to the complete lack of input validation in +os.makedirs, and it's calling of the os.mkdir() built-in, which +may vary depending on the python compilation: + + + + +Source: +def makedirs(name, mode=0777): + """makedirs(path [, mode=0777]) + + Super-mkdir; create a leaf directory and all intermediate ones. + Works like mkdir, except that any intermediate path segment (not + just the rightmost) will be created if it does not exist. This is + recursive. + """ + head, tail = path.split(name) + if not tail: + head, tail = path.split(head) + if head and tail and not path.exists(head): + try: + makedirs(head, mode) + except OSError, e: + # be happy if someone already created the path + if e.errno != errno.EEXIST: + raise + if tail == curdir: # xxx/newdir/. exists if xxx/newdir exists + return + mkdir(name, mode) + + + + + + + + + +9.2 def _open_subprocess(self, args, passphrase=False) vuln + + + + + + +9.2.1 L515: unvalidated_user_input + + ++cmd.extend(args) + + + + + cmd is a list of strings, eventually joined with cmd=' '.join(cmd), and + the args are unvalidated in this function. Then this concatenation of args + is fed directly into subprocess.Popen(cmd, shell=True, stdin=PIPE, + stdout=PIPE, stderr=PIPE). THIS SHOULD BE PATCHED. + + + + + + + +9.3 def _collect_output(self, process, result, writer=None, stdin=None) + + + sends stdout to self._read_data() and stderr to self._read_response() + + + + + + +9.4 def _handle_io(self, args, file, result, passphrase=None, binary=False) vuln cleanup + + + + + + +9.4.1 L601: unvalidated_user_input type_check_in_call + + ++p = self._open_subprocess(args, passphrase is not None) + + + + + you shouldn't assign or type check in a function call + + + + + + + +9.5 def sign(self, message, **kwargs) cleanup + + + + + + +9.5.1 L617-619: hanging_fd + + + calls self._make_binary_stream(), which leaves the file descriptor for + the encoded message to be encrypted hanging between scopes. + + + + + + + +9.6 def sign_file(self, file, keyid=None, passphrase=None, clearsign=True, detach=False, binary=False) cleanup + + + + + + +9.6.1 L632-635: bad_logic + + + + + +if detach: + args.append("--detach-sign") +elif clearsign: + args.append("--clearsign") + + + + + the logic here allows that if a user erroneously specifies both options, + rather than doing what the system gnupg would do (that is, do –clearsign, + and ignore the –attach-sign), python-gnupg would ignore both. + + + + + + +9.6.2 L626-641: + + + input 'args' into self._open_subprocess() is defined as static strings. + + + + + + + +9.7 def verify(self, data): cleanup + + + + + + +9.7.1 L668-670: hanging_fd + + + same hanging file descriptor problem as in self.sign() + + + + + + + +9.8 def verify_file(self, file, data_filename=None) vuln cleanup + + + + + + +9.8.1 L683: hanging_fd + + + more potentially hanging file descriptors… + + + + + +9.8.2 L684: hanging_fd + + + oh look, another hanging file descriptor. imagine that. + + + + + +9.8.3 L690: unvalidated_user_input + + ++args.append('"%s"' % data_filename) + + + well, there's the exploit. see included POC script. + + + + + + + +9.9 def import_keys(self, key_data) vuln + + + + + + +9.9.1 L749: unvalidated_user_input + + + this function could potentially allow an attacker with a GPG exploit to + use it, because it passes key generation parameter directly into the + internal packet parsers of GPG. however, without a GPG exploit for one of + the GPG packet parsers (for explanation of GPG packets look into pgpdump), + this function alone is not exploitable. + + + + + + + +9.10 def recieve_keys(self, keyserver, *keyids) vuln + + + + + + +9.10.1 L770: unvalidated_user_input + + ++args.extend(keyids) + + + + + + + + + +9.11 def export_keys(self, keyids, secret=False) vuln + + + + + + +9.11.1 L795-796: unvalidated_user_input + + + args problem again. exploitable though parameter ``keyids``. + + + + + + + +9.12 def list_keys(self, secret=False) + + + + + + +9.12.1 L827: + + + args is static string. + + + + + + + +9.13 def gen_key(self, input) cleanup + + + + + + +9.13.1 L864: + + + args, passed to self._handle_io(), which in turn passes args directly to + Popen(), is set to a static string. this function is halfway okay, though + it really could be more careful with the ``input`` parameter. + + + + + + + +9.14 def gen_key_input(self, **kwargs) vuln + + + + + + +9.14.1 L981-983: unvalidated_user_input + + + this function could potentially allow an attacker with a GPG exploit to + use it, because it passes key generation parameter directly into the + internal packet parsers of GPG. however, without a GPG exploit for one of + the GPG packet parsers (for explanation of GPG packets look into pgpdump), + this function alone is not exploitable. + + + + + + + +9.15 def encrypt_file(self, file, recipiencts, sign=None, …) vuln + + + + + + +9.15.1 L939: unvalidated_user_input + + + several of the inputs to this function are unvalidated, turned into + strings, and passed to Popen(). exploitable. + + + + + + + +9.16 def encrypt(self, data, recipients, **kwargs): vuln + + + + + + +9.16.1 L997: unvalidated_user_input + + + exploitable, passes kwargs to self.encrypt_file() + + + + + + + +9.17 def decrypt(self, message **kwargs): vuln + + + + + + +9.17.1 L1003: unvalidated_user_input + + + kwargs are passed to self.decrypt_file(), unvalidated, making this + function also exploitable + + + + + + + +9.18 def decrypt_file(self, file, always_trust=False, passphrase=None, output=None) vuln + + + + + + +9.18.1 L1013: unvalidated_user_input + + + unvalidated user input: this function is also exploitable + + + + + + + + +10 POC + + +CANNOT INCLUDE FILE ../python-gnupg-0.3.1/python-gnupg-exploit.py + + + + + +Date: 2013-02-01 Fri +Author: isis +isis@leap.se +Org version 7.9.2 with Emacs version 24 +Validate XHTML 1.0 + + + + diff --git a/docs/NOTES-python-gnupg-3.1-audit.org b/docs/NOTES-python-gnupg-3.1-audit.org new file mode 100644 index 0000000..b80fb39 --- /dev/null +++ b/docs/NOTES-python-gnupg-3.1-audit.org @@ -0,0 +1,232 @@ +#+TITLE: python-gnupg audit +#+AUTHOR: isis +#+EMAIL: isis@leap.se +#+DATE: 2013-02-01 Fri +#+DESCRIPTION: +#+KEYWORDS: +#+LANGUAGE: en +#+OPTIONS: H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t +#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc +#+INFOJS_OPT: view:nil toc:2 ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js +#+EXPORT_SELECT_TAGS: export +#+EXPORT_EXCLUDE_TAGS: noexport +#+LINK_UP: +#+LINK_HOME: +#+XSLT: + +[2013-02-01 Fri] + +* gnugp.__main__() +** comments +L58 NullHandler?? see self._write_passphrase +L61 there nifty check for p3k +** def _copy_data(instream, outstream) :cleanup: + copies data from one stream to another, 1024 bytes at a time. +*** L79: :bad_logic: + instream is apparently a file descriptor, but is not checked nor + encased in a try/except block. + +*** L78: :hanging_fd:bad_logic: + while True: loop, should be + : with open(instream) as instrm: +*** L88: :bad_exception_handling: + : except: + should catch an IOError, or whatever specific error is raised for broken + pipes. +** def _threaded_copy_data(instream, outstream): +*** L99: + this just wraps self._copy_data in a thread +** def _write_passphrase(stream, passphrase, encoding): :vuln:cleanup: +*** L110: :writes_passphrase_to_disk: + logger writes passphrase into debug log. this should be patched. +* class Verify(object) + basic parsing class, no errors found +* class ImportResult(object) + basic parsing class, no errors found +* class ListKeys(list): + basic parsing class, no errors found +* class Crypt(Verify): + basic parsing class, no errors found +** def __init__(self, gpg) :cleanup: +*** L338 :mro_conflict: + + #+BEGIN_SRC python + Verify.__init__(self,gpg) + #+END_SRC + + should be changed to: + + #+BEGIN_SRC python + super(Verify, self).__init__(gpg) + #+END_SRC +* class GenKey(object) + basic parsing class, no errors found +* class DeleteResult(object) + basic parsing class, no errors found +* class Sign(object) + basic parsing class, no errors found +* class GPG(object) :exploitable: +*** L474: :cleanup: + : cls.__doc__ + should go directly underneath class signature +** def __init__(self, gpgbinary='gpg', gnupghome=None, verbose=False, use_agent=False, keyring=None) :bug: +*** L494-495: :type_error: + + #+BEGIN_SRC python + if gnupghome and not os.path.isdir(self.gnupghome): + os.makedirs(self.gnupghome,0x1C0) + #+END_SRC + + #+BEGIN_EXAMPLE + In [20]: os.makedirs? + Type: function + String Form: + File: /usr/lib/python2.7/os.py + Definition: os.makedirs(name, mode=511) + Docstring: + makedirs(path [, mode=0777]) + Super-mkdir; create a leaf directory and all intermediate ones. + Works like mkdir, except that any intermediate path segment (not + just the rightmost) will be created if it does not exist. This is + recursive. + + setting mode=0x1c0 is equivalent to mode=hex(0700), which + may cause bugs on some systems, see + http://ubuntuforums.org/showthread.php?t=2044879 + + this could be do to the complete lack of input validation in + os.makedirs, and it's calling of the os.mkdir() built-in, which + may vary depending on the python compilation: + #+END_EXAMPLE + + #+BEGIN_SRC python + Source: + def makedirs(name, mode=0777): + """makedirs(path [, mode=0777]) + + Super-mkdir; create a leaf directory and all intermediate ones. + Works like mkdir, except that any intermediate path segment (not + just the rightmost) will be created if it does not exist. This is + recursive. + """ + head, tail = path.split(name) + if not tail: + head, tail = path.split(head) + if head and tail and not path.exists(head): + try: + makedirs(head, mode) + except OSError, e: + # be happy if someone already created the path + if e.errno != errno.EEXIST: + raise + if tail == curdir: # xxx/newdir/. exists if xxx/newdir exists + return + mkdir(name, mode) + #+END_SRC + +** def _open_subprocess(self, args, passphrase=False) :vuln: +*** L515: :unvalidated_user_input: + : cmd.extend(args) + + cmd is a list of strings, eventually joined with cmd=' '.join(cmd), and + the args are unvalidated in this function. Then this concatenation of args + is fed directly into subprocess.Popen(cmd, shell=True, stdin=PIPE, + stdout=PIPE, stderr=PIPE). THIS SHOULD BE PATCHED. + +** def _collect_output(self, process, result, writer=None, stdin=None) + sends stdout to self._read_data() and stderr to self._read_response() + +** def _handle_io(self, args, file, result, passphrase=None, binary=False) :vuln:cleanup: +*** L601: :unvalidated_user_input:type_check_in_call: + : p = self._open_subprocess(args, passphrase is not None) + + you shouldn't assign or type check in a function call + +** def sign(self, message, **kwargs) :cleanup: +*** L617-619: :hanging_fd: + calls self._make_binary_stream(), which leaves the file descriptor for + the encoded message to be encrypted hanging between scopes. + +** def sign_file(self, file, keyid=None, passphrase=None, clearsign=True, detach=False, binary=False) :cleanup: +*** L632-635: :bad_logic: + #+BEGIN_SRC python + if detach: + args.append("--detach-sign") + elif clearsign: + args.append("--clearsign") + #+END_SRC + + the logic here allows that if a user erroneously specifies both options, + rather than doing what the system gnupg would do (that is, do --clearsign, + and ignore the --attach-sign), python-gnupg would ignore both. + +*** L626-641: + input 'args' into self._open_subprocess() is defined as static strings. + +** def verify(self, data): :cleanup: +*** L668-670: :hanging_fd: + same hanging file descriptor problem as in self.sign() + +** def verify_file(self, file, data_filename=None) :vuln:cleanup: +*** L683: :hanging_fd: + more potentially hanging file descriptors... +*** L684: :hanging_fd: + oh look, another hanging file descriptor. imagine that. +*** L690: :unvalidated_user_input: + : args.append('"%s"' % data_filename) + well, there's the exploit. see included POC script. + +** def import_keys(self, key_data) :vuln: +*** L749: :unvalidated_user_input: + this function could potentially allow an attacker with a GPG exploit to + use it, because it passes key generation parameter directly into the + internal packet parsers of GPG. however, without a GPG exploit for one of + the GPG packet parsers (for explanation of GPG packets look into pgpdump), + this function alone is not exploitable. + +** def recieve_keys(self, keyserver, *keyids) :vuln: +*** L770: :unvalidated_user_input: + : args.extend(keyids) + +** def export_keys(self, keyids, secret=False) :vuln: +*** L795-796: :unvalidated_user_input: + args problem again. exploitable though parameter ``keyids``. + +** def list_keys(self, secret=False) +*** L827: + args is static string. + +** def gen_key(self, input) :cleanup: +*** L864: + args, passed to self._handle_io(), which in turn passes args directly to + Popen(), is set to a static string. this function is halfway okay, though + it really could be more careful with the ``input`` parameter. + +** def gen_key_input(self, **kwargs) :vuln: +*** L981-983: :unvalidated_user_input: + this function could potentially allow an attacker with a GPG exploit to + use it, because it passes key generation parameter directly into the + internal packet parsers of GPG. however, without a GPG exploit for one of + the GPG packet parsers (for explanation of GPG packets look into pgpdump), + this function alone is not exploitable. + +** def encrypt_file(self, file, recipiencts, sign=None, ...) :vuln: +*** L939: :unvalidated_user_input: + several of the inputs to this function are unvalidated, turned into + strings, and passed to Popen(). exploitable. + +** def encrypt(self, data, recipients, **kwargs): :vuln: +*** L997: :unvalidated_user_input: + exploitable, passes kwargs to self.encrypt_file() + +** def decrypt(self, message **kwargs): :vuln: +*** L1003: :unvalidated_user_input: + kwargs are passed to self.decrypt_file(), unvalidated, making this + function also exploitable + +** def decrypt_file(self, file, always_trust=False, passphrase=None, output=None) :vuln: +*** L1013: :unvalidated_user_input: + unvalidated user input: this function is also exploitable + +* POC +#+INCLUDE: "../python-gnupg-0.3.1/python-gnupg-exploit.py" python diff --git a/docs/NOTES-python-openpgp-implementations.txt b/docs/NOTES-python-openpgp-implementations.txt new file mode 100644 index 0000000..bf60728 --- /dev/null +++ b/docs/NOTES-python-openpgp-implementations.txt @@ -0,0 +1,31 @@ +-*- mode: org -*- + +* Other Python OpenPGP libraries and utilities: + +*** pygpgme - https://launchpad.net/pygpgme +A limited set of Python wrappers around GPGME +http://www.gnupg.org/documentation/manuals/gpgme/ + +*** py-gnupg - https://github.com/kevinoid/py-gnupg/blob/master/GnuPGInterface.py +Focuses mainly on using file handles to interact with GnuPG. + +*** OpenPGP-Python - https://github.com/singpolyma/OpenPGP-Python +The commit messages are a bit worrysome and the code has some scary +error-prone-looking method chaining going on, a five minute glance over the +/OpenPGP/Crypto.py file and it appears this is actually a valid OpenPGP +implementation, built using D.Litzenberger's PyCrypto library. +https://github.com/dlitz/pycrypto + +This person also wrote OpenPGP-Haskell: +https://github.com/singpolyma/OpenPGP-Haskell + +...and OpenPGP-PHP (/horrorface): https://github.com/singpolyma/openpgp-php and +an HTTP server as a shell script with a pretty crazy pipe hack. + +...and kudos on this one, it's an attempt at a mnemnonic system for squaring +Zooko's Triangle (L17 being a function named "countLeadingCrapAndZeros"): +https://github.com/singpolyma/mnemonicode/blob/master/mnencode.c#L17 + +* GnuPG unattended key generation scripts: + +*** mandos-keygen http://bzr.recompile.se/loggerhead/mandos/trunk/annotate/523/mandos-keygen?start_revid=616 diff --git a/docs/OpenPGP-keys-in-DNS.md b/docs/OpenPGP-keys-in-DNS.md new file mode 100644 index 0000000..56cb542 --- /dev/null +++ b/docs/OpenPGP-keys-in-DNS.md @@ -0,0 +1,133 @@ +[Christoph Berg's Blog](../index.html)/ + +[2007](../2007.html)/ + + + +OpenPGP keys in DNS + + + + + + + + +* [RecentChanges](../recentchanges.html) +* [History](http://svn.df7cb.de/viewcvs.cgi/trunk/2007/openpgp-dns.mdwn?root=blog&view=log) + + + + + + + + +The latest addition to the mutt CVS tree is PKA support via gpgme. While trying +to figure out how that works in mutt (I haven't yet...) I configured my DNS +server for PKA and CERT records. + +## PKA + +PKA (public key association) puts a pointer where to obtain a key into a TXT +record. At the same time that can be used to verify that a key belongs to a +mail address. The documentation is at the +[g10code website](http://www.g10code.de/docs/pka-intro.de.pdf) +(only in German so far). I put the following into the df7cb.de zone: + + +cb._pka IN TXT "v=pka1;fpr=D224C8B07E63A6946DA32E07C5AF774A58510B5A;uri=finger:cb@df7cb.de" + + +$ host -t TXT cb._pka.df7cb.de +cb._pka.df7cb.de descriptive text "v=pka1\;fpr=D224C8B07E63A6946DA32E07C5AF774A58510B5A\;uri=finger:cb@df7cb.de" + + +Now gpg can be told to use PKA to find the key: + ++$ echo foo | gpg --auto-key-locate pka --recipient cb@df7cb.de --encrypt -a +gpg: no keyserver known (use option --keyserver) +gpg: requesting key 58510B5A from finger:cb@df7cb.de +gpg: key 58510B5A: public key "Christoph Berg " imported +gpg: Total number processed: 1 +gpg: imported: 1 +gpg: automatically retrieved `cb@df7cb.de' via PKA + + +## CERT + +CERT records work similarly. Records are generated by make-dns-cert (from the +tools directory in the gnupg source). cb.gpg is a stripped-down gpg keyring +(created with pgp-clean -s and converting from .asc to .gpg). + ++$ ./make-dns-cert -f D224C8B07E63A6946DA32E07C5AF774A58510B5A -n cb +cb TYPE37 \# 26 0006 0000 00 14 D224C8B07E63A6946DA32E07C5AF774A58510B5A +$ ./make-dns-cert -k cb.gpg -n cb +cb TYPE37 \# 1338 0003 0000 00 9901A20440 [...] 509C96D4BFF17B7 + + +With a new bind and host (backports.org!) the format looks a bit nicer, that's +also what I copied into the zone file: + ++$ host -t CERT cb.df7cb.de +;; Truncated, retrying in TCP mode. +cb.df7cb.de has CERT record PGP 0 0 mQGiBECBGdAR [...] UDlCcltS/8Xtw== +cb.df7cb.de has CERT record 6 0 0 FNIkyLB+Y6aUbaMuB8Wvd0pYUQta + + +Again, gpg can be told to use that: + ++$ echo foo | gpg --auto-key-locate cert --recipient cb@df7cb.de --encrypt -a +gpg: key 58510B5A: public key "Christoph Berg " imported +gpg: Total number processed: 1 +gpg: imported: 1 +gpg: automatically retrieved `cb@df7cb.de' via DNS CERT + + +Thanks to weasel for some hints on using CERT. + +## SSHFP + +I'm also mentioning SSHFP records here since it fits in the topic - I have been +using them for some months now: + ++$ host -t SSHFP tesla.df7cb.de +tesla.df7cb.de has SSHFP record 1 1 EE49B803541293656C33B86ECD781BD8F1D78AB5 +tesla.df7cb.de has SSHFP record 2 1 3E82FB5EE8AA0205305F0D0186F94D6FB3E0E744 +$ ssh -o 'VerifyHostKeyDNS yes' tesla.df7cb.de +The authenticity of host 'tesla.df7cb.de (88.198.227.218)' can't be established. +RSA key fingerprint is 5a:c9:38:ca:c0:2b:11:c1:c8:fb:f1:ad:73:a1:9c:8b. +Matching host key fingerprint found in DNS. +Are you sure you want to continue connecting (yes/no)? + + +The records are generated with ssh-keygen -r. + + + + + + + + + + +Tags: + +[debian](../tag/debian.html) + + + + +Last edited Do 17 Feb 2011 13:21:52 CET + + + + + + diff --git a/docs/_static/DETAILS.html b/docs/_static/DETAILS.html new file mode 100644 index 0000000..7b0b9f8 --- /dev/null +++ b/docs/_static/DETAILS.html @@ -0,0 +1,2677 @@ + + + + +GnuPG Details + + + + + + + + + +

python-gnupg audit

Table of Contents

1 gnugp._main_()

1.1 comments

1.2 def copydata(instream, outstream) cleanup

1.2.1 L79: bad_logic

1.2.2 L78: hanging_fd bad_logic

1.2.3 L88: bad_exception_handling

1.3 def threadedcopydata(instream, outstream):

1.3.1 L99:

1.4 def writepassphrase(stream, passphrase, encoding): vuln cleanup

1.4.1 L110: writes_passphrase_to_disk

2 class Verify(object)

3 class ImportResult(object)

4 class ListKeys(list):

5 class Crypt(Verify):

5.1 def _init_(self, gpg) cleanup

5.1.1 L338 mro_conflict

6 class GenKey(object)

7 class DeleteResult(object)

8 class Sign(object)

9 class GPG(object) exploitable

9.1 L474: cleanup

9.1 def _init_(self, gpgbinary='gpg', gnupghome=None, verbose=False, useagent=False, keyring=None) bug

9.1.1 L494-495: type_error

9.2 def opensubprocess(self, args, passphrase=False) vuln

9.2.1 L515: unvalidated_user_input

9.3 def collectoutput(self, process, result, writer=None, stdin=None)

9.4 def handleio(self, args, file, result, passphrase=None, binary=False) vuln cleanup

9.4.1 L601: unvalidated_user_input type_check_in_call

9.5 def sign(self, message, **kwargs) cleanup

9.5.1 L617-619: hanging_fd

9.6 def signfile(self, file, keyid=None, passphrase=None, clearsign=True, detach=False, binary=False) cleanup

9.6.1 L632-635: bad_logic

9.6.2 L626-641:

9.7 def verify(self, data): cleanup

9.7.1 L668-670: hanging_fd

9.8 def verifyfile(self, file, datafilename=None) vuln cleanup

9.8.1 L683: hanging_fd

9.8.2 L684: hanging_fd

9.8.3 L690: unvalidated_user_input

9.9 def importkeys(self, keydata) vuln

9.9.1 L749: unvalidated_user_input

9.10 def recievekeys(self, keyserver, *keyids) vuln

9.10.1 L770: unvalidated_user_input

9.11 def exportkeys(self, keyids, secret=False) vuln

9.11.1 L795-796: unvalidated_user_input

9.12 def listkeys(self, secret=False)

9.12.1 L827:

9.13 def genkey(self, input) cleanup

9.13.1 L864:

9.14 def genkeyinput(self, **kwargs) vuln

9.14.1 L981-983: unvalidated_user_input

9.15 def encryptfile(self, file, recipiencts, sign=None, …) vuln

9.15.1 L939: unvalidated_user_input

9.16 def encrypt(self, data, recipients, **kwargs): vuln

9.16.1 L997: unvalidated_user_input

9.17 def decrypt(self, message **kwargs): vuln

9.17.1 L1003: unvalidated_user_input

9.18 def decryptfile(self, file, alwaystrust=False, passphrase=None, output=None) vuln

9.18.1 L1013: unvalidated_user_input

10 POC

1 gnugp.__main_₍₎

1.2 def _copy_data(instream, outstream) cleanup

1.3 def _threaded_copy_data(instream, outstream):

1.4 def _write_passphrase(stream, passphrase, encoding): vuln cleanup

5.1 def init{(self, gpg)} cleanup

9.1 def init{(self, gpgbinary='gpg', gnupghome=None, verbose=False, use_agent=False, keyring=None)} bug

9.2 def _open_subprocess(self, args, passphrase=False) vuln

9.3 def _collect_output(self, process, result, writer=None, stdin=None)

9.4 def _handle_io(self, args, file, result, passphrase=None, binary=False) vuln cleanup

9.6 def sign_file(self, file, keyid=None, passphrase=None, clearsign=True, detach=False, binary=False) cleanup

9.8 def verify_file(self, file, data_filename=None) vuln cleanup

9.9 def import_keys(self, key_data) vuln

9.10 def recieve_keys(self, keyserver, *keyids) vuln

9.11 def export_keys(self, keyids, secret=False) vuln

9.12 def list_keys(self, secret=False)

9.13 def gen_key(self, input) cleanup

9.14 def gen_key_input(self, **kwargs) vuln

9.15 def encrypt_file(self, file, recipiencts, sign=None, …) vuln

9.18 def decrypt_file(self, file, always_trust=False, passphrase=None, output=None) vuln