Struct didcomm_rs::Message

pub struct Message { /* private fields */ }

DIDComm message structure.

Messages are used to construct new DIDComm messages.

A common flow is

• creating a message
• setting different properties with chained setters
• serializing the message to one of the following formats:
  • a plain DIDComm message
  • a signed JWS envelope
  • an encrypted JWE envelope
  • a sealed and encrypted JWE envelope

For examples have a look here.

Specification

Implementations

impl Message

pub fn apeend_attachment(&mut self, builder: AttachmentBuilder)

Appends attachment into attachments field. Consumes instance of AttachmentBuilder to do so.

Parameters

• builder - prepopulated instance of AttachmentBuilder

pub fn get_attachments(&self) -> impl DoubleEndedIterator<Item = &Attachment>

Returns iterator of all attachments, if any. If no attachment present - empty iterator will be returned.

impl Message

pub fn new() -> Self

Generates EMPTY default message. Use extension messages to build final one before sending.

pub fn add_header_field(self, key: String, value: String) -> Self

Adds (or updates) custom unique header key-value pair to the header. This portion of header is not sent as JOSE header.

pub fn as_flat_jwe(
    self,
    alg: &CryptoAlgorithm,
    recipient_public_key: Option<Vec<u8>>
) -> Self

Sets message to be serialized as flat JWE JSON. If this message has multiple targets, sealing it will result in an Error.

pub fn as_flat_jws(self, alg: &SignatureAlgorithm) -> Self

Sets message to be serialized as flat JWS JSON and then calls as_jws. If this message has multiple targets, sealing it will result in an Error.

pub fn get_message_uri(&self) -> String

Shortcut to DidCommHeader::get_message_uri

pub fn reply_to(self, replying_to: &Self) -> Self

Sets thid and pthid same as those in replying_to Shortcut to DidCommHeader::reply_to method

• replying_to - ref to message we’re replying to

pub fn with_parent(self, parent: &Self) -> Self

Sets pthid to the parent’s thid. It defaults to id if thid is missing.

Parameters

• parent - ref to a parent threaded Message

pub fn as_jwe(
    self,
    alg: &CryptoAlgorithm,
    recipient_public_key: Option<Vec<u8>>
) -> Self

Setter of from header Helper method.

For resolve feature will set kid header automatically based on the did document resolved.

pub fn as_jws(self, alg: &SignatureAlgorithm) -> Self

Creates set of JWM related headers for the JWE Modifies JWM related header portion to match encryption implementation and leaves other parts unchanged. TODO + FIXME: complete implementation

pub fn body(self, body: &str) -> Self

Setter of the body. Note, that given text has to be a valid JSON string to be a valid body value.

pub fn didcomm_header(self, h: DidCommHeader) -> Self

Setter of didcomm_header. Replaces existing one with provided by consuming both values. Returns modified instance of Self.

pub fn from(self, from: &str) -> Self

Setter of from header.

pub fn get_body(&self) -> Result<String, Error>

Getter of the body as String.

pub fn get_didcomm_header(&self) -> &DidCommHeader

&DidCommHeader getter.

pub fn get_jwm_header(&self) -> &JwmHeader

&JwmCommHeader getter.

pub fn get_prior(&self) -> Result<PriorClaims, Error>

If message is_rotation() true - returns from_prion claims. Errors otherwise with Error::NoRotationData

pub fn is_rotation(&self) -> bool

Checks if message is rotation one. Exposed for explicit checks on calling code level.

pub fn jwm_header(self, h: JwmHeader) -> Self

Setter of jwm_header. Replaces existing one with provided by consuming both values. Returns modified instance of Self.

pub fn m_type(self, m_type: &str) -> Self

Setter of m_type @type header

pub fn typ(self, typ: MessageType) -> Self

Setter of typ header property.

Parameters

• typ - MessageType to be set for typ property

pub fn kid(self, kid: &str) -> Self

pub fn timed(self, expires: Option<u64>) -> Self

Sets times of creation as now and, optional, expires time.

Arguments

• expires - time in seconds since Unix Epoch when message is considered to be invalid.

pub fn to(self, to: &[&str]) -> Self

Setter of to header

pub fn set_didcomm_header(self, h: DidCommHeader) -> Self

Setter of didcomm_header. Replaces existing one with provided by consuming both values. Returns modified instance of Self.

pub fn get_application_params(&self) -> impl Iterator<Item = (&String, &String)>

Gets Iterator over key-value pairs of application level headers

pub fn thid(self, thid: &str) -> Self

Setter of thid header

pub fn pthid(self, pthid: &str) -> Self

Setter of pthid header

impl Message

pub fn as_raw_json(self) -> Result<String, Error>

Serializes current state of the message into json. Consumes original message - use as raw sealing of envelope.

pub fn export_for_encryption(&self) -> Result<(Vec<u8>, Vec<u8>), Error>

Presents IV and Payload to be externally encrypted and then sealed with seal_pre_encrypted method.

Returns

Tuple of bytes where .0 is IV and .1 is payload for encryption

pub fn seal_pre_encrypted(
    self,
    cyphertext: impl AsRef<[u8]>
) -> Result<String, Error>

Builds JWE from current message and it’s pre-encrypted payload: expert_for_encryption should be used prior to this call and it’s output provided as payload.

Parameters

ciphertext - encrypted output of export_for_encryption as JWE payload

Returns serialized JSON JWE message, which is ready to be sent to receipent

pub fn receive(
    incoming: &str,
    encryption_recipient_private_key: Option<&[u8]>,
    encryption_sender_public_key: Option<Vec<u8>>,
    signing_sender_public_key: Option<&[u8]>
) -> Result<Self, Error>

Construct a message from received data. Raw, JWS or JWE payload is accepted.

Arguments

• incoming - serialized message as Message/Jws/Jws

• encryption_recipient_private_key - recipients private key, used to decrypt kek in JWE

• encryption_sender_public_key - senders public key, used to decrypt kek in JWE

• signing_sender_public_key - senders public key, the JWS envelope was signed with

pub fn routed_by(
    self,
    sender_private_key: &[u8],
    recipient_public_keys: Option<Vec<Option<Vec<u8>>>>,
    mediator_did: &str,
    mediator_public_key: Option<Vec<u8>>
) -> Result<String, Error>

Wrap self to be mediated by some mediator. Warning: Should be called on a Message instance which is ready to be sent! If message is not properly set up for crypto - this method will propagate error from called .seal() method. Takes one mediator at a time to make sure that mediated chain preserves unchanged. This method can be chained any number of times to match all the mediators in the chain.

Arguments

• sender_private_key - encryption key for inner message payload JWE encryption

• recipient_public_keys - keys used to encrypt content encryption key for recipient; can be provided if key should not be resolved via recipients DID

• mediator_did - DID of message mediator, will be to of mediated envelope

• mediator_public_key - key used to encrypt content encryption key for mediator; can be provided if key should not be resolved via mediators DID

pub fn seal(
    self,
    sender_private_key: impl AsRef<[u8]>,
    recipient_public_keys: Option<Vec<Option<Vec<u8>>>>
) -> Result<String, Error>

Seals (encrypts) self and returns ready to send JWE

Arguments

• sender_private_key - encryption key for inner message payload JWE encryption

• recipient_public_keys - keys used to encrypt content encryption key for recipient; can be provided if key should not be resolved via recipients DID

impl Message

Associated functions implementations. Possibly not required as Jwe serialization covers this.

pub fn get_iv(received: &[u8]) -> Result<Vec<u8>, Error>

Parses iv value as Vec<u8> from public header. Both regular JSON and Compact representations are accepted. Returns Error on failure. TODO: Add examples

pub fn received_as_jwe(incomming: impl AsRef<[u8]>) -> Option<Jwe>

Transforms incomming into Jwe if it is one Also checks if skid field is present or returns None othervise Key resolution and validation fall onto caller of this method

Parameters

• incomming - incomming message

Returns Option<Jwe> where .header.skid is skid and .payload() is cyphertext

pub fn receive_external_crypto(
    decrypted: impl AsRef<[u8]>
) -> Result<Self, Error>

Transforms decrypted Jwe into Message

Parameters

• decrypted - result of decrypting of Jwe payload retreived after decrypting content of as_jwe function call output.

pub fn seal_signed(
    self,
    encryption_sender_private_key: &[u8],
    encryption_recipient_public_keys: Option<Vec<Option<Vec<u8>>>>,
    signing_algorithm: SignatureAlgorithm,
    signing_sender_private_key: &[u8]
) -> Result<String, Error>

Signs raw message and then packs it to encrypted envelope Spec

Arguments

• encryption_sender_private_key - encryption key for inner message payload JWE encryption

• encryption_recipient_public_keys - keys used to encrypt content encryption key for recipient with; can be provided if key should not be resolved via recipients DID

• signing_algorithm - encryption algorithm used

• signing_sender_private_key - signing key for enveloped message JWS encryption

impl Message

pub fn encrypt(
    self,
    crypter: SymmetricCypherMethod,
    cek: &[u8]
) -> Result<String, Error>

Encrypts current message by consuming it. Uses provided cryptography function to perform the encryption. Agnostic of actual algorithm used. Consuming is to make sure no changes are possible post packaging / sending. Returns (JwmHeader, Vec<u8>) to be sent to recipient.

Arguments

• crypter - encryptor that should be used

• cek - content encryption key to encrypt message with

pub fn decrypt(
    received_message: &[u8],
    decrypter: SymmetricCypherMethod,
    cek: &[u8]
) -> Result<Self, Error>

Decrypts received cypher into instance of Message. Received message should be encrypted with our pub key. Returns Ok(Message) if decryption / deserialization succeeded. Error otherwise.

Arguments

• received_message - received message as byte array

• decrypter - decrypter that should be used

• cek - content encryption key to decrypt message with

pub fn sign(
    self,
    signer: SigningMethod,
    signing_sender_private_key: &[u8]
) -> Result<String, Error>

Signs message and turns it into Jws envelope. Err is returned if message is not properly prepared or data is malformed. Jws enveloped payload is base64_url encoded

pub fn verify(
    jws: &[u8],
    signing_sender_public_key: &[u8]
) -> Result<Message, Error>

Verifies signature and returns payload message on verification success. Err return if signature invalid or data is malformed. Expects Jws’s payload to be a valid serialized Message and base64_url encoded.

pub fn verify_value(
    jws: &Value,
    signing_sender_public_key: &[u8]
) -> Result<Message, Error>

Verifies signature and returns payload message on verification success. Err return if signature invalid or data is malformed. Expects Jws’s payload to be a valid serialized Message and base64_url encoded.

Arguments

• jws - to be verified jws message as json Value object

• signing_sender_public_key - optional public key used for verification, if None it will try to resolve the did in the kid field

impl Message

pub fn as_out_of_band_invitation(
    self,
    body: impl AsRef<[u8]>,
    attachments: Option<Vec<AttachmentBuilder>>
) -> Self

Transforms given Message into out_of_band invitation with given body and optional attachments.

Parameters

• body - bytes of JSON serialized message body
• attachments - optional set of AttachmentBuilder to be attached

Trait Implementations

impl Clone for Message

fn clone(&self) -> Message

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Message

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Message

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<Message> for Message

fn eq(&self, other: &Message) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Message) -> bool

This method tests for !=.

impl Serialize for Message

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Message