Skip to content
Browse files

Docu updates

  • Loading branch information...
geertj committed Aug 9, 2013
1 parent a939242 commit 596a0aee4866369c857d1313c117ee333b403e10
Showing with 34 additions and 158 deletions.
  1. +5 −133 docs/messagebus.txt
  2. +29 −25 docs/objects.txt
@@ -1,137 +1,9 @@
Message Bus

The communication between the Bluepass frontend and backend takes place via a
message bus. The message bus runs over a socket and transfers JSON messages in
both directions. The protocol is loosely modeled after D-BUS model but it is
The communication between the Bluepass frontend and backend takes place via the
JSON-RPC protocol.

Why not use D-BUS? Because we need to support platforms where D-BUS is not
available by default, and i don't want to be required to provide packages for
those platforms.

Message Exchanges

1. Method calls

A method call is initiated by the following message::

'type': 'method_call',
'serial': serial_number
'sender': 'sender_name',
'destination': 'destination_name',
'member': 'method_name',
'args': {}

The sender/destination fields specify the connection names (see below) of the
sender and the destination. The method field specifies the method to call. The
serial field is an integer that needs to be unique for each message generated
by this sender. The 'args' field is an object containing keyword arguments to
the method call.

A peer will reply to a 'method_call' message with a single 'method_return'

'type': 'method_return',
'serial': serial_number',
'reply_serial': reply_serial_number,
'sender': 'sender_name',
'destination': 'destination_name',
'args': {}

The significance of the fields is as for a "method_call" message. In addition
"reply_serial" field identifies the message this method_return is a reply to.

If there is an error, the 'error' message is returned instead of a

'type': 'error',
'serial': serial_number',
'reply_serial': reply_serial_number,
'sender': 'sender_name',
'destination': 'destination_name',
'args': {
'error_name': 'string_id',
'error_message': 'textual error message'

The format is as for a "method_return" message with the addition that the
"args" field is guaranteed to have at least the "error_name" and the
"error_message" fields.

2. Signals

A signal is an asynchronous message that is not a reply to a method call but
instead signals an asynchronous condition that has happened::

'type': 'signal',
'serial': serial_number',
'sender': 'sender_name',
'destination': 'destination_name',
'member': 'signal_name',
'args': {}

The "destination" field for a signal is optional. If it is not set, it means
that the signal was sent to multiple connections on the message bus.

Connection Names

Each end point for the message bus connection has a name. The local name is
simply called the "name", and the remote name is called the "peer_name". The
local name is the peer name of the peer, and vice versa.

The server (= listening) side of a connection chooses a name before accepting
connections. The name chosen by the Bluepass backend is 'backend'. The client
(= connecting) side get a unique name from the server side during


A simple, mutual authentication scheme based on HMAC and a shared secret is
implemented. The protocol uses the "authenticate" message to establish the
authentication. No message types other than "authenticate" may travel over the
connection before a connection is authenticated.

The client starts the authentication handshake like this:

'type': 'authenticate',
'method': 'hmac-magic-cookie-sha1',
'nonce': 'random_string',
'magic_cookie': 'cookie'

The value of "magic_cookie" is the HMAC of the nonce under the shared secret
and using the SHA1 hash function.

The server will respond to the handshake with this message::

'type': 'authenticate',
'method': 'hmac-magic-cookie-sha1',
'nonce': 'random_string_2',
'magic_cookie': 'cookie',
'name': 'name of server',
'peer_name': 'name assigned to client'

The client then uses the 'nonce' and 'magic_cookie' to authenticate the server.
In case of an authentication error (at either side), the connection must be

The mechanism for sharing the secret is not specified. Currently the backend
and the frontend are always started up by the same master process, so that can
generate the secret and share it with both sides.
Currently the protocol is not authenticated, which is OK in the default
configuration where a Unix domain socket with restricted permissions is used.
Protocol-level authentication and authorization should be added later.
@@ -1,10 +1,9 @@
# This file is a reference for the schema of the objects stored in the
# database.

# Store the vault/node/version unencrypted. This is required because we need
# it for efficient replication, and one of the security assumptions we have is
# that we do not

# vaults collection: this is not replicated
# The vaults collection: this is not replicated. Each vault contains the
# following fields:

'id': 'uuid',
@@ -14,28 +13,32 @@
'keys': {
'sign': {
'keytype': 'rsa',
'public': 'base64(asn1)',
'private': 'base64(encrypt(asn1,key,iv))',
'public': 'b64(pubkey_asn1)',
'private': 'b64(aes_encrypt(privkey_asn1, key, iv))',
'encinfo': {
'algo': 'aes-cbc-pkcs5',
'iv': 'base64(random)'
'kdf': 'pbkdf2-hmac-sha1',
'salt': 'base64(random)'
'count': n,
'length': bytes,
'iv': 'b64(random())'
'kdf': 'pbkdf2-hmac-sha256',
'salt': 'b64(random())'
'count': itercount,
'length': keysize,
'pwcheck': {
'algo': 'hmac-magic-cookie-sha1',
'random': 'base64(random)',
'cookie': 'base64(hmac(key,random))'
'algo': 'hmac-random-sha256',
'random': 'b64(random())',
'cookie': 'b64(hmac(key, random))'
'encrypt': { /* as sign */ },
'auth': { /* as sign */ },

# items collection: this is replicated
# The items collection: this is replicated. Each item is as follows:
# The signature is over the entire item, minus only the signature blob,
# serialized as json in pure ASCII with sorted keys and no whitespace.

'id': 'uuid',
'_type': 'Item',
@@ -49,8 +52,8 @@
'signature': {
'algo': 'rsa-pss-sha1',
'blob': 'xxx'
'algo': 'rsa-pss-sha256',
'blob': 'b64(rsa_sign(canon(message), sign_key))'

@@ -62,19 +65,20 @@
'node': 'uuid',
'name': 'name',
'keys': {
'sign': { 'key': 'xxx', 'keytype': 'rsa' }
'encrypt': { 'key': 'xxx', 'keytype': 'rsa' }
'sign': { 'key': 'b64(sign_pubkey)', 'keytype': 'rsa' }
'encrypt': { 'key': 'b64(encrypt_pubkey)', 'keytype': 'rsa' }
'auth': { 'key': 'b64(auth_pubkey)', 'keytype': 'rsa' }
'restrictions': { 'synconly': false }

'_type': 'EncryptedPayload'
'algo': 'aes-cbc-pkcs5',
'iv': 'xxxx',
'blob': 'yyyy'
'iv': 'b64(random())',
'blob': 'b64(aes_encrypt(contents, symkey, iv))'
'keyalgo': 'rsa-oaep',
'keys' : { 'uuid': 'rsa encrypted symkey', ... }
'keys' : { 'uuid': 'b64(rsa_encrypt(symkey, node_encrypt_pubkey))', ... }

0 comments on commit 596a0ae

Please sign in to comment.
You can’t perform that action at this time.