serde-encrypt

:closedlockwith_key: Encrypts all the Serialize.

text Alice Bob +-----------------------------------+ +-----------------------------------+ | #[derive(Serialize, Deserialize)] | | #[derive(Serialize, Deserialize)] | | struct Message {} | | struct Message {} | +-----------------------------------+ +-----------------------------------+ | .encrypt() ^ v | ::decrypt() +-----------------------------------+ +-----------------------------------+ | struct EncryptedMessage | | struct EncryptedMessage | +-----------------------------------+ +-----------------------------------+ | .serialize() ^ v | ::deserialize() +-----------------------------------+ +-----------------------------------+ | struct Vec<u8> | -----> | struct Vec<u8> | +-----------------------------------+ +-----------------------------------+

Overview

serde-encrypt encrypts/decrypts any strcts and enums that implements serde::{Serialize, Deserialize}.

serde-encrypt supports both shared-key encryption (XChaCha20-Poly1305) and public-key encryption (XChaCha20-Poly1305 with X25513 key-exchange), both of which are considered to be secure enough.

serde-encrypt is optionally available in no_std environments.

toml Cargo.toml [dependencies] serde-encrypt = "(version)" # If you use std serde-encrypt = {version = "(version)", default-features = false} # If you need no_std

Example

If you and your peer already have shared-key, just implement SerdeEncryptSharedKey trait to your Serialize and Deserialize data types.

```rust

[derive(Debug, Serialize, Deserialize)]

struct Message { content: String, sender: String, }

impl SerdeEncryptSharedKey for Message {} ```

Then, you can serialize the Message into Vec<u8> in encrypted form.

```rust let shared_key = [0u8; 32]; // or read from your filesystem?

let msg = Message {
    content: "I ❤️ you.".to_string(),
    sender: "Alice".to_string(),
};
let encrypted_message = msg.encrypt(&shared_key)?;
let serialized_encrypted_message: Vec<u8> = encrypted_message.serialize()?;

```

After your peer gets the binary, he or she can decrypt and deserialize it to Message.

```rust let shared_key = [0u8; 32]; // or your peer reads from filesystem?

let encrypted_message = EncryptedMessage::deserialize(serialized_encrypted_message)?;
let msg = Message::decrypt_owned(&encrypted_message, &shared_key)

```

Further examples...

• 👀 Encrypts struct with reference fields
• 🔑 Generates shared-key and safely exchange it to your peer. And then, encrypt/decrypt messages using the shared-key.
• 📚 Encrypts/Decrypts complex serde types

Features and uses cases

Feature comparison

| | SerdeEncryptSharedKey | SerdeEncryptPublicKey | | --------------------- | ----------------------- | ----------------------- | | (a)symmetric? | symmetric | asymmetric | | deterministic? (*1) | no | no | | performance | high | low |

(*1) Deterministic encryptions always produce the same cipher-text from a given plain-text. Usable for equal-matching in cipher-text (e.g. RDBMS's encrypted index eq-search).

Encryption algorithm

| | SerdeEncryptSharedKey | SerdeEncryptPublicKey | | -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | key exchange | - | X25519 | | encryption | XChaCha20 | XChaCha20 | | message auth | Poly1305 | Poly1305 | | nonce (*2) | XSalsa20 (random 24-byte) | XSalsa20 (random 24-byte) | | Rng (*3) for nonce | ChaCha20Rng | ChaCha20Rng | | Implementation | XChaCha20Poly1305 | ChaChaBox |

(*2) "Number used once": to make encryption non-deterministic. Although nonce for each encryption is not secret, nonce among different encryption must be different in order for attackers to harder to guess plain-text.

(*3) Random number generator.

Serialization

| | SerdeEncryptSharedKey | SerdeEncryptPublicKey | | ------------- | ----------------------------------------------------- | ----------------------------------------------------- | | serialization | CBOR | CBOR |

Use cases

• SerdeEncryptedSharedKey
  • Both message sender and receiver already hold shared key.
  • Needs shared-key exchange via any safe way but wants high-speed encryption/decryption (e.g. communicates large amounts of messages).
• SerdeEncryptedSharedKey
  • To exchange SharedKey.
  • Quickly sends/receive small amounts of messages without secret shared key.

std vs no_std

This crate comes with std feature by default. To enable no_std mode, specify default-features = false in your Cargo.toml.

toml Cargo.toml [dependencies] serde-encrypt = {version = "(version)", default-features = false}

Here is a list of what std featue brings to you.

• std::error::Error trait implementation to serde_encrypt::error::Error.

Changelog

See CHANGELOG.md.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in serde-encrypt by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.