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

; Version 1
Envelope = [
    version : uint,
    mac     : bstr,
    message : bstr ; Message as embedded CBOR.
]

Message

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

Plain message

PlainMessage = (
    session-tag      : bstr,
    counter          : uint,
    previous-counter : uint,
    ratchet-key      : bstr,
    cipher-text      : bstr
)

PreKey message

PreKeyMessage = (
    prekey-id    : uint,
    base-key     : bstr, ; public key
    identity-key : bstr, ; public key
    PlainMessage
)

PreKey bundle

; Version 1
PreKeyBundle = [
    version             : uint,
    prekey-id           : uint,
    public-key          : bstr,
    public-identity-key : bstr
]

PreKey

; Version 1
PreKey = [
    version    : uint,
    prekey-id  : uint,
    secret-key : bstr,
    public-key : bstr
]

Identity key

; Version 1
IdentityKey = [
    version    : uint,
    secret-key : bstr,
    public-key : bstr
]

Session

; Version 1
Session = [
    version         : uint,
    session-tag     : bstr,
    local-identity  : bstr, ; public key
    remote-identity : bstr, ; public key
    pending-prekey  : ?[ prekey-id: uint, public-key: bstr ],
    session-states  : [+ SessionState ]
]

Session state

SessionState = (
    session-tag          : bstr,
    receive-chains       : [+ ReceiveChain ],
    send-chain           : SendChain
    root-key             : bstr,
    counter              : uint,
    skipped-message-keys : [* MessageKeys ]
)

Receive chain

ReceiveChain = (
    ChainKey,
    ratchet-key : bstr
)

Send chain

SendChain = (
    ChainKey,
    secret-ratchet_key : bstr,
    public-ratchet_key : bstr
)

Chain key

ChainKey = (
    mac-key : bstr,
    counter : uint
)

Message keys

MessageKeys = (
    cipher-key : bstr,
    mac-key    : bstr,
    counter    : uint
)