Crate sodoken

source ·
Expand description

lib SOdium + haDOKEN = SODOKEN!

libsodium wrapper providing tokio safe memory secure api access.

Project Forum Chat

License: MIT License: Apache-2.0

This crate-level documentation mainly describes how to work with the sodoken buffer types. Please see the individual module-level documentation for usage examples and descriptions of individual crypto functions.

§Sodoken Buffers

Sodoken buffers provide implementors with the ability to optionally use secured memory (mlock + mprotect) to mitigate some secret exposure channels like disk swapping. Buffers created with new_mem_locked are secured, buffers created with new_no_lock are not.

Please note that on most systems, locked memory is a finite resource, so you should use it for private keys, but not everything.

All buffers are shallow-cloned by default, so buf.clone() or any of the buf.to_*() apis will give you a reference to the same buffer. You can deep clone the buffers with the buf.deep_clone_mem_locked() or buf.deep_clone_no_lock() apis.

In general, the steps for working with sodoken apis are:

  • create a writable buffer
  • shallow clone that buffer into an api
  • translate that buffer into a read-only version for future use
§Buffer Example
// create a writable buffer
let salt: sodoken::BufWriteSized<{ sodoken::hash::argon2id::SALTBYTES }> =
    sodoken::BufWriteSized::new_no_lock();

// shallow clone that buffer into an api
sodoken::random::bytes_buf(salt.clone()).await.unwrap();

// translate that buffer into a read-only version for future use
let salt = salt.to_read_sized();

Modules§

  • buffer
    Additional types related to working with buffers.
  • crypto_box
    Modules related to cryptographic box encryption / decryption.
  • hash
    Modules related to hashing.
  • kdf
    Api functions related to cryptographically secure key derivation.
  • kx
    Api functions related to cryptographically secure key exchange.
  • random
    Api functions related to cryptographically secure randomness / entropy.
  • secretbox
    Modules related to cryptographic secretbox encryption / decryption.
  • secretstream
    Modules related to secret stream encryption / decryption.
  • sign
    Api functions related to cryptographic signatures and verification.

Structs§

  • BufExtend
    A concrete extendable buffer type that may or may not be mem_locked.
  • BufRead
    A concrete read-only buffer type that may or may not be mem_locked.
  • BufReadSized
    A concrete sized read-only buffer type that may or may not be mem_locked.
  • BufWrite
    A concrete writable buffer type that may or may not be mem_locked.
  • BufWriteSized
    A concrete sized writable buffer type that may or may not be mem_locked.

Enums§

Type Aliases§