Serialisation format

Serialisation format

Proteus uses CBOR (RFC 7049) as its serialisation format. The following sections describe the serialised structure definitions using CDDL syntax.

Envelope

Envelope = {
    0: uint, ;; Version
    1: Mac,
    2: bstr  ;; Message as embedded CBOR.
}

Message

Message = (1, PlainMessage) / (2, PreKeyMessage)

Plain message

PlainMessage = {
    0: bstr,      ;; Session tag
    1: uint,      ;; Counter (u32)
    2: uint,      ;; Previous counter (u32)
    3: PublicKey, ;; Ratchet key
    4: bstr       ;; Cipher text
}

PreKey message

PreKeyMessage = {
    0: uint,       ;; Prekey ID (u16)
    1: PublicKey,
    2: IdentityKey
    PlainMessage
}

PreKey bundle

PreKeyBundle = {
    0: uint,        ;; Version
    1: uint,        ;; Prekey ID (u16)
    2: PublicKey,
    3: IdentityKey,
    4: ?Signature   ;; Signature of public key
}

PreKey

PreKey = {
    0: uint,      ;; Version
    1: uint,      ;; Prekey ID (u16)
    2: SecretKey,
    3: PublicKey  ;; Public key
}

Identity key

IdentityKey = {
    0: uint,      ;; Version
    1: SecretKey,
    2: PublicKey
}

Session

Session = {
    0: uint,      ;; Version
    1: bstr,      ;; Session tag
    2: PublicKey, ;; Local identity
    3: PublicKey, ;; Remote identity public key
    4: ?{
        0: uint,     ;; Prekey ID
        1: PublicKey ;; Public prekey
    },
    5: {+ bstr => SessionState } ;; Map of session tags to session states
}

Session state

SessionState = {
    0: [+ ReceiveChain ],
    1: SendChain
    2: RootKey
    3: uint               ;; Counter
}

Receive chain

ReceiveChain = {
    0: ChainKey,
    1: PublicKey,       ;; Ratchet key
    2: [* MessageKeys ] ;; Skipped message keys
}

Send chain

SendChain = {
    0: ChainKey,
    1: KeyPair
)

Chain key

ChainKey = {
    0: MacKey
    1: uint  ;; Counter
}

Message keys

MessageKeys = {
    0: CipherKey,
    1: MacKey,
    2: uint       ;; Counter
)

Various

KeyPair   = { 0: SecretKey, 1: PublicKey }
PublicKey = { 0: bstr }
SecretKey = { 0: bstr }
Signature = { 0: bstr }
Mac       = { 0: bstr }
MacKey    = { 0: bstr }
CipherKey = { 0: bstr }