dco3-crypto

DRACOON Crypto utils in Rust
Documentation »
Report Bug

dco3-crypto

What is this?

Work in progress Crypto library for DRACOON based on openssl crate.

Breaking changes are most likely at this early stage - the library is under heavy development and depends on requirements from dco3 (currently private API wrapper for DRACOON). Changes will be documented in the release notes.

What does work?

• Asymmetric encryption / decryption of file keys (RSA)
• Keypair generation (RSA)
• Keypair encryption / decryption (RSA)
• Symmetric encryption / decryption of messages (AES256 GCM)
  • on the fly encryption / decryption
  • chunked encryption / decryption

What is planned?

• Refactor asymmetric encryption (split keypair generation from other operations)
• Use other libraries like ring as alternative to openssl bindings
• Add feature flags to cargo build
• Add e2e tests using encryption data from other SDKs / libs and ensure compatibility in pipeline

What is shipped?

Using the crate currently binds to the latest openssl version and is compiled in vendored mode (see openssl for details).

How to use?

See crates.io TL;DR Add the following line to your Cargo.toml file (dependencies): toml dco3_crypto = "0.4.0"

Documentation

Documentation All detailed documentation is provided via docs on docs.rs

TL; DR usage

Required imports

The lib consists of several traits that are all (currently only) implemented by the DracoonCrypto struct. Therefore, the minimum required import is always DracoonCrypto and the relevant required trait (DracoonRSACrypto, Encrypt, Decrypt, ChunkedEncryption, Encrypter, Decrypter).

Asymmetric encryption

In order to - generate a (plain) user keypair - en/decrypt a user keypair - encrypt a private only - encrypt a file key with a public key (user keypair) - decrypt a file key with a private key (user keypair)

Generate a plain user keypair:

```rust use dco3_crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion};

// RSA2048 is only supported for legacy compatibility // always use UserKeypairVersion::RSA4096 let newkeypair = DracoonCrypto::createplainuserkeypair(UserKeyPairVersion::RSA4096).unwrap();

```

Encrypt a plain user keypair:

```rust use dco3_crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion};

let newkeypair = DracoonCrypto::createplainuserkeypair(UserKeyPairVersion::RSA4096).unwrap(); let secret ="VerySecret123!"; let enckeypair = DracoonCrypto::encryptprivatekey(secret, newkeypair).unwrap();

```

Encrypt a private key only:

```rust use dco3_crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion};

let newkeypair = DracoonCrypto::createplainuserkeypair(UserKeyPairVersion::RSA4096).unwrap(); let secret ="VerySecret123!"; let encprivatekey = DracoonCrypto::encryptprivatekeyonly(secret, newkeypair.privatekeycontainer).unwrap();

```

Decrypt a protected user keypair: ```rust use dco3_crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion};

let newkeypair = DracoonCrypto::createplainuserkeypair(UserKeyPairVersion::RSA4096).unwrap(); let secret ="VerySecret123!"; let enckeypair = DracoonCrypto::encryptprivatekey(secret, newkeypair).unwrap(); let plainkeypair = DracoonCrypto::decryptprivatekey(secret, enckeypair).unwrap();

```

Encrypt a file key using either a plain user keypair or a public key container:

```rust use dco3crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion, Encrypt}; let newkeypair = DracoonCrypto::createplainuser_keypair(UserKeyPairVersion::RSA4096).unwrap();

// encrypt a message to get a plain file key for demo purposes let message = b"Secret message"; let (encmessage, plainfilekey) = DracoonCrypto::encrypt(message.tovec()).unwrap();

// the function also accepts a public key container as argument let encfilekey = DracoonCrypto::encryptfilekey(plainfilekey, plain_keypair).unwrap(); ```

Decrypt the file key using a plain user keypair: ```rust use dco3crypto::{DracoonCrypto, DracoonRSACrypto, UserKeypairVersion, Encrypt}; let newkeypair = DracoonCrypto::createplainuser_keypair(UserKeyPairVersion::RSA4096).unwrap();

// encrypt a message to get a plain file key for demo purposes let message = b"Secret message"; let (encmessage, plainfilekey) = DracoonCrypto::encrypt(message.tovec()).unwrap();

// the function also accepts a public key container as argument let encfilekey = DracoonCrypto::encryptfilekey(plainfilekey, plain_keypair).unwrap();

// this code is for demo purposes - plainkeypair is consumed above and needs to be // instantiated again let plainfilekey = DracoonCrypto::decryptfilekey(encfilekey, plainkeypair).unwrap(); ```

Symmetric encryption

Symmetric encryption is represented by the following traits:

• Encrypt: needed for in-memory encryption
• Decrypt: needed for in-memory decryption
• Decrypter: needed to build a decrypter capable of chunked decryption
• Encrypter: needed to build an encrypter capable of chunked encryption
• ChunkedEncryption: needed for both en- and decryption when using a decrypter / encrypter

Encrypt a message on the fly:

```rust use dco3_crypto::{DracoonCrypto, Encrypt};

// encrypt a message to get a plain file key for demo purposes let message = b"Secret message"; let (encmessage, plainfilekey) = DracoonCrypto::encrypt(message.tovec()).unwrap();

// to encrypt the file key, see asymmetric encryption above ```

Decrypt a message on the fly:

```rust use dco3_crypto::{DracoonCrypto, Encrypt, Decrypt};

// encrypt a message to get a plain file key for demo purposes let message = b"Secret message"; let (encmessage, plainfilekey) = DracoonCrypto::encrypt(message.tovec()).unwrap();

// to decrypt / encrypt the file key, see asymmetric encryption above let plainmessage = DracoonCrypto::decrypt(&encmessage, plainfilekey); ```

Encrypt in chunks:

```rust use dco3crypto::{DracoonCrypto, Encrypter, ChunkedEncryption}; let mut message = b"Encrypt this very long message in chunks and decrypt it"; let bufflen = message.len() + 1; let mut buf = vec![0u8; buff_len]; let mut encrypter = DracoonCrypto::encrypter(&mut buf).unwrap(); let mut count: usize = 0;

// chunks of 8 bytes const CHUNKSIZE: usize = 8; let mut chunks = message.chunks(CHUNKSIZE); while let Some(chunk) = chunks.next() { count += encrypter.update(&chunk).unwrap(); };

count += encrypter.finalize().unwrap(); let encmessage = encrypter.getmessage(); let plainfilekey = encrypter.getplainfile_key();

```

Decrypt in chunks:

```rust // importing Encrypt is only necessary for the inital message encryption use dco3_crypto::{DracoonCrypto, Encrypt, Decrypter, ChunkedEncryption}; use openssl::symm::Cipher; let message = b"Encrypt this very long message in chunks and decrypt it";

let (message, plainfilekey) = DracoonCrypto::encrypt(message.tovec()).unwrap(); let bufflen = message.len() + 1;

let mut chunks = message.chunks(5); let mut buf = vec![0u8; bufflen]; let mut decrypter = DracoonCrypto::decrypter(plainfile_key, &mut buf).unwrap(); let mut count: usize = 0; while let Some(chunk) = chunks.next() { count += decrypter.update(&chunk).unwrap(); }

count += decrypter.finalize().unwrap();

let plainmessage = std::str::fromutf8(decrypter.get_message()).unwrap();

```