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: bstr, ;; MAC
    2: bstr  ;; Message as embedded CBOR.
}

Message

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

Plain message

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

PreKey message

PreKeyMessage = {
    0: uint, ;; Prekey ID
    1: bstr, ;; Public Base key
    2: bstr, ;; Public Identity key
    PlainMessage
}

PreKey bundle

PreKeyBundle = {
    0: uint, ;; Version
    1: uint, ;; Prekey ID
    2: bstr, ;; Public key
    3: bstr  ;; Public identity key
}

PreKey

PreKey = {
    0: uint, ;; Version
    1: uint, ;; Prekey ID
    2: bstr, ;; Secret key
    3: bstr  ;; Public key
}

Identity key

IdentityKey = {
    0: uint, ;; Version
    1: bstr, ;; Secret key
    2: bstr  ;; Public key
}

Session

Session = {
    0: uint,  ;; Version
    1: bstr,  ;; Session tag
    2: bstr,  ;; Local identity public key
    3: bstr,  ;; Remote identity public key
    4: ?{
        0: uint, ;; Prekey ID
        1: bstr  ;; Public prekey
    },
    5: [+ SessionState ]
}

Session state

SessionState = {
    0: bstr,              ;; Session tag
    1: [+ ReceiveChain ],
    2: SendChain
    3: bstr,              ;; Root key
    4: uint,              ;; Counter
    5: [* MessageKeys ]   ;; Skipped message keys
}

Receive chain

ReceiveChain = {
    0: ChainKey,
    1: bstr      ;; Ratchet key
}

Send chain

SendChain = {
    0: ChainKey,
    1: bstr, ;; Secret ratchet key
    2: bstr  ;; Public ratchet key
)

Chain key

ChainKey = {
    0: bstr, ;; MAC key
    1: uint ;; Counter
}

Message keys

MessageKeys = {
    0: bstr, ;; Cipher key
    1: bstr, ;; MAC key
    2: uint  ;; Counter
)