Struct xaynet_core::message::MessageBuffer

pub struct MessageBuffer<T> { /* fields omitted */ }

A wrapper around a buffer that contains a Message.

It provides getters and setters to access the different fields of the message safely. A message is made of a header and a payload:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                           signature                           +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                         participant_pk                        +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                         coordinator_pk                        +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                             length                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      tag      |                    reserved                   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                    payload (variable length)                  +
|                                                               |

• signature contains the signature of the entire message
• participant_pk contains the public key for verifying the signature
• coordinator_pk is the coordinator public encryption key. It is embedded in the message for security reasons. See Donald T. Davis, "Defective Sign & Encrypt in S/MIME, PKCS#7, MOSS, PEM, PGP, and XML.", Proc. Usenix Tech. Conf. 2001 (Boston, Mass., June 25-30, 2001)
• length is the length in bytes of the full message, i.e. including the header. This is a 32 bits field so in theory, messages can be as big as 2^32 = 4,294,967,296 bytes.
• tag indicates the type of message (sum, update, sum2 or multipart message)

Examples

Reading a sum message

use std::convert::TryFrom;
use xaynet_core::message::{MessageBuffer, Tag};

let mut bytes = vec![0x11; 64]; // message signature
bytes.extend(vec![0x22; 32]); // participant public signing key
bytes.extend(vec![0x33; 32]); // coordinator public encrypt key
bytes.extend(&200_u32.to_be_bytes()); // Length field
bytes.push(0x01); // tag (sum message)
bytes.extend(vec![0x00, 0x00, 0x00]); // reserved

// Payload: a sum message contains a signature and an ephemeral public key
bytes.extend(vec![0xaa; 32]); // signature
bytes.extend(vec![0xbb; 32]); // public key

let buffer = MessageBuffer::new(&bytes).unwrap();
assert_eq!(buffer.signature(), vec![0x11; 64].as_slice());
assert_eq!(buffer.participant_pk(), vec![0x22; 32].as_slice());
assert_eq!(buffer.coordinator_pk(), vec![0x33; 32].as_slice());
assert_eq!(Tag::try_from(buffer.tag()).unwrap(), Tag::Sum);
assert_eq!(
    buffer.payload(),
    [vec![0xaa; 32], vec![0xbb; 32]].concat().as_slice()
);

Writing a sum message

use std::convert::TryFrom;
use xaynet_core::message::{MessageBuffer, Tag};

let mut expected = vec![0x11; 64]; // message signature
expected.extend(vec![0x22; 32]); // participant public signing key
expected.extend(vec![0x33; 32]); // coordinator public signing key
expected.extend(&200_u32.to_be_bytes()); // length field
expected.push(0x01); // tag (sum message)
expected.extend(vec![0x00, 0x00, 0x00]); // reserved

// Payload: a sum message contains a signature and an ephemeral public key
expected.extend(vec![0xaa; 32]); // signature
expected.extend(vec![0xbb; 32]); // public key

let mut bytes = vec![0; expected.len()];
let mut buffer = MessageBuffer::new_unchecked(&mut bytes);
buffer
    .signature_mut()
    .copy_from_slice(vec![0x11; 64].as_slice());
buffer
    .participant_pk_mut()
    .copy_from_slice(vec![0x22; 32].as_slice());
buffer
    .coordinator_pk_mut()
    .copy_from_slice(vec![0x33; 32].as_slice());
buffer.set_length(200 as u32);
buffer.set_tag(Tag::Sum.into());
buffer
    .payload_mut()
    .copy_from_slice([vec![0xaa; 32], vec![0xbb; 32]].concat().as_slice());
assert_eq!(expected, bytes);

Implementations

impl<T: AsRef<[u8]>> MessageBuffer<T>

pub fn inner(&self) -> &T

pub fn as_ref(&self) -> MessageBuffer<&T>

pub fn new(bytes: T) -> Result<Self, DecodeError>

Performs bound checks for the various message fields on bytes and returns a new MessageBuffer.

Errors

Fails if the bytes are smaller than a minimal-sized message buffer.

pub fn new_unchecked(bytes: T) -> Self

Returns a MessageBuffer without performing any bound checks.

This means accessing the various fields may panic if the data is invalid.

pub fn check_buffer_length(&self) -> Result<(), DecodeError>

Performs bound checks to ensure the fields can be accessed without panicking.

pub fn tag(&self) -> u8

Gets the tag field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn length(&self) -> u32

Gets the length field

Panics

Accessing the field may panic if the buffer has not been checked before.

impl<'a, T: AsRef<[u8]> + ?Sized> MessageBuffer<&'a T>

pub fn signature(&self) -> &'a [u8]

Gets the message signature field

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn participant_pk(&self) -> &'a [u8]

Gets the participant public key field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn coordinator_pk(&self) -> &'a [u8]

Gets the coordinator public key field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn payload(&self) -> &'a [u8]

Gets the rest of the message.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn check_signature(&self) -> Result<(), DecodeError>

Parse the signature and public signing key, and check the message signature.

pub fn signed_data(&self) -> &'a [u8]

Return the portion of the message used to compute the signature, ie the entire message except the signature field itself.

Panics

Accessing the field may panic if the buffer has not been checked before.

impl<T: AsMut<[u8]> + AsRef<[u8]>> MessageBuffer<T>

pub fn set_tag(&mut self, value: u8)

Sets the tag field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn set_length(&mut self, value: u32)

Sets the length field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn signature_mut(&mut self) -> &mut [u8]

Gets a mutable reference to the message signature field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn participant_pk_mut(&mut self) -> &mut [u8]

Gets a mutable reference to the participant public key field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn coordinator_pk_mut(&mut self) -> &mut [u8]

Gets a mutable reference to the coordinator public key field.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn payload_mut(&mut self) -> &mut [u8]

Gets a mutable reference to the rest of the message.

Panics

Accessing the field may panic if the buffer has not been checked before.

pub fn signed_data_mut(&mut self) -> &mut [u8]

Gets a mutable reference to the portion of the message used to compute the signature, ie the entire message except the signature field itself.

Panics

Accessing the field may panic if the buffer has not been checked before.