[tor-dev] Various Tor keys, their formats, and usages [was: Bridge Bandwidth Scanner Internship]

Tue Aug 8 00:36:02 UTC 2017

Hello!

The following was my attempt last week to summarise all of our various keys
in server descriptors, how they are formatted, and what they are used for,
in the hopes that this is useful in alleviating possible future confusions
for others.

Let me know (and, more importantly! let Jake know since he's writing a Rust
parser for bridge descriptors as part of the Bridge Bandwidth Scanner
project) if I got anything wrong. :)

----- Forwarded message from isis agora lovecruft <isis at torproject.org> -----

> From: isis agora lovecruft <isis at torproject.org>
> Subject: Re: Bridge Bandwidth Scanner Internship
> Date: Thu, 27 Jul 2017 19:52:47 +0000
> Message-ID: <20170727195247.GI24882 at patternsinthevoid.net>
> To: jnz at riseup.net
> Reply-To: isis at torproject.org
> Delivered-To: <isis+torproject at patternsinthevoid.net>
> 
> jnz at riseup.net transcribed 1.4K bytes:
> > Hey Isis,
> > 
> > I have started the sanitization spec and the parser. A lot of the stuff
> > I had to learn for the two overlaps, so I am working on them
> > simultaneously. Conceptually, I understand the sanitization process, but
> > I am a little bit confused about what some of the fields are in the
> > descriptors.
> > 
> > Q1. What exactly is the difference between "master-key", "identity-key",
> > and "signing-key"?
> > 
> > After reading through the descriptor spec, cert spec, and other docs, I
> > am pretty confused on what each of the above means.I'm using the Nom
> > crate for the parser, I've never used it before but so far I'm really
> > liking it. Have you ever used it?
> 
> This is specified (not all that well, imho) in dir-spec.txt… it's really
> confusing.
> 
> For versions of tor new enough to have prop#220 and prop#228 (>0.2.7.2-alpha):
> 
>  - "identity-ed25519" is a certificate containing a base64-encoded ed25519
>    key. The bridge uses this to authenticate to clients.
> 
>  - "master-key-ed25519" is the ed25519 key which is in the
>    "identity-ed25519" certificate.
> 
>  - "onion-key" is an RSA-1024 key, encoded as a PKCS#1 RSAPublicKey
>    structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC
>    KEY-----" and "-----END RSA PUBLIC KEY-----".  This key is used to
>    encrypt CREATE cells to in the older TAP handshake protocol. (TAP is
>    almost entirely unused on the network, last I checked.  We'll likely be
>    removing "onion-key"s in the next year or so, after we EOL some old tor
>    versions.)
> 
>  - "ntor-onion-key" is a public curve25519 key, base64-encoded. This is used
>    in the newer NTor handshake protocol, which replaced TAP. It is still
>    quite common to see routers which have both an "onion-key" and an
>    "ntor-onion-key".
> 
>  - "signing-key" is the same type and format as "onion-key" above, but it's
>    used as a long-term identity key, for authenticating the bridge to
>    clients. (Similar to "identity-ed25519" just with RSA signatures.)
> 
>  - "router-sig-ed255519" is a only present iff "identity-ed25519" is
>    present, and it's an ed25519 signature of a SHA-256 digest of the
>    "entire" descriptor (Minus the "@purpose bridge" header since the Bridge
>    Authority is the one who adds that. So from "router " on the first line
>    up to and including the first space after "router-sig-ed25519".)  This
>    "entire" descriptor is first prefixed with the string "Tor router
>    descriptor signature v1" before hashing and signing.  After the signature
>    is produced, it is encoded in base64 and the trailing "="s are removed.
> 
>  - "router-signature" contains a signature of the PKCS#1-padded SHA-1 digest
>     of the "entire" server descriptor, taken from the beginning of the
>     "router" line (skipping "@purpose bridge" again), through (and
>     including) the newline after the "router-signature" line.  The signature
>     is made with the router's "signing-key" (a.k.a. identity key).
> 
> For older tor versions (without prop220 and/or prop228):
> 
>  - They will have "onion-key", "ntor-onion-key", "signing-key", and
>    "router-signature", as above.
> 
> I've attached a tarball of today's descriptors for this bridge from the
> public/default bridges in Tor Browser:
> 
> https://atlas.torproject.org/#details/FEC8FB380DABA9D3C80790B634E4540BF5D09CCA
> 
> Let me know if you want some more examples!  I only grabbed one because they
> are pretty annoying to pull out of the giant, unordered, undeduplicated
> files the BridgeAuth produces (at least without writing a full parser).
> 
> Also lmk if you have more questions, the entangled ball of crypto junk we
> shove into descriptors is pretty confusing.

[…snip…]

----- End forwarded message -----

Best regards,
-- 
 ♥Ⓐ isis agora lovecruft
_________________________________________________________
OpenPGP: 4096R/0A6A58A14B5946ABDE18E207A3ADB67A2CDB8B35
Current Keys: https://fyb.patternsinthevoid.net/isis.txt
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 2017-07-27-ndnop3-descriptors.tar.xz
Type: application/x-xz
Size: 4320 bytes
Desc: not available
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20170808/718f73b2/attachment.xz>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 1240 bytes
Desc: Digital signature
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20170808/718f73b2/attachment.sig>