secret-handshake
secure-channel based on a a mutually authenticating key agreement handshake, with forward secure identity metadata.
For a full explanation of the design, read the
Design Paper
Implementations
- javascript/node.js this repo.
- go cryptix/secretstream
- rust AljoschaMeyer/secret-handshake-rs
- c AljoschaMeyer/shs1-c (actually just implements the crypto, not the protocol used as a component in the rust implementation)
- python/twisted david415/txsecrethandshake (WIP)
- C Kodest/cshs
- C++ Kodest/cppshs (WIP)
- also keks/tamarin-shs is a formal proof of the cryptographic properties!
Claims
This protocol derives shared keys and mutually
authenticates both ends of the connection.
The shared secrets are forward secure, and
so is the identity metadata.
by "forward secure identity metadata" I mean:
- a later key compromise cannot confirm the public keys in the handshake.
And also:
- an eavesdropper cannot learn public keys
- replay attacker cannot learn public keys.
- man in the middle cannot learn public keys.
- a "wrong number" cannot learn public keys.
- an unauthenticated client cannot learn server key.
note: a wrong number is just an accidental man in the middle.
By "confirm" I mean check a guess at the public key.
By "learn" I mean that you can either extract the public key,
or confirm the public key.
Also note that if the server decides not to authenticate a client,
it will learn their public key. To get to this stage, the client
must know the server's key, so now the client and server both
know each others key. This is fair.
Disclaims
This protocol cannot hide your ip address.
This protocol does not attempt to obscure packet boundries.
If a man in the middle or wrong number later compromises
the server's key, they will be able to extract the client
key from the client's hello packet.
Example
var SHS = require('secret-handshake')
var cl = require('chloride')
var appKey = ... //32 random bytes
var alice = cl.crypto_sign_keypair() //client
var bob = cl.crypto_sign_keypair() //server
function authorize(id, cb) {
cb(null, check(id)) //check wether id is authorized.
}
//initialize, with default timeouts.
var ServerStream = SHS.createServer(alice, authorize, appKey)
var ClientStream = SHS.createClient(bob, appkey)
var alice_stream = ServerStream(function (err, stream) {
...
})
var bob_stream = ClientStream(alice.publicKey, function (err, stream) {
...
})
//simulate a streaming network connection by connecting streams together
pull(alice_stream, bob_stream, alice_stream)
Notes
I recommend using secret-handshake via multiserver
pull-streams are used.
Learn about how pull-streams from these examples
Keypairs are expected to be of the form sodium produces.
chloride is my fork of this and is compatible.
If you're interested in the protocol, you can read more here : https://ssbc.github.io/scuttlebutt-protocol-guide/#handshake
api
createClient(keypair, authorize, appkey, timeout) => createClientStream(key, seed?, cb(err, plainstream)) => cipherstream
createClient takes:
keypair- a keypair of form{ secretKey, publicKey }- your clients keys (seechloride#crypto_sign_keypair)appkey- the network identifier, 32 random bytestimeout- an integer (in milliseconds? CHECK THIS)
and returns a createClientStream
createClientStream takes a the public key for the remote peer,
an optional seed (which is used to generate a one-time private key),
and a callback, cb. cipherstream, an encrypted duplex pull-stream is returned.
Once the stream is connected to a server stream,
secret-handshake will attempt to authorize, and will call
cb with an err if it fails, or plainstream if it succeeds.
If keypair is null, seed must be provided.
createServer(keypair, authorize(id, cb), appkey, timeout) => createServerStream(cb(err, plain_stream)) => cipherstream
createServer is similar, except it takes authorize,
keypair- a keypair of form{ secretKey, publicKey }(seechloride#crypto_sign_keypair)authorize- an async function of signature(id, cb)that decides whether a client with id == publicKey is allowed to continue with handshakeappkey- the network identifier, 32 random bytestimeout- an integer (in milliseconds? CHECK THIS)
A stream constructor function is returned
Note the server DOES NOT take the client id as an argument - instead, in the process
of the handshake, the server learns the id, and passes it to authorize.
If authorize calls back truthy, then it will callback cb(null, plainstream)
else it errors, cb(err).
The value that authorize calls back cb(null, <V>) will be assigned to plainstream.auth = <V>.
Also, the id of the remote will be assigned to plainstream.id.
This way the application layer can know who it's peer is.
License
MIT