philbin 1.0.1

A pure Rust AEGIS library with SIMD and runtime CPU detection
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

#![doc = include_str!("rustdoc/crate_doc.md")]
#![deny(missing_docs)]
#![deny(clippy::all)]
#![deny(clippy::doc_markdown)]
#![deny(clippy::missing_errors_doc)]
#![deny(clippy::missing_panics_doc)]
#![deny(clippy::must_use_candidate)]
#![deny(clippy::missing_safety_doc)]
#![deny(clippy::return_self_not_must_use)]
#![deny(clippy::semicolon_if_nothing_returned)]

mod aligned_buffer;
mod arch;
mod auth_tag;
mod base;
mod error;
mod facade;
mod key;
mod newtypes;
mod nonce;
mod utils;

// All external-facing APIs are part of either "easy" or "careful" modules.

/// Easy, high-level APIs that are hard to misuse.
///
/// See the "Get Started" section in [the crate
/// docs][crate#get-started-with-the-easy-module].
pub mod easy {
  pub use crate::arch::is_hw_accelerated;
  pub use crate::auth_tag::AuthTag;
  pub use crate::auth_tag::AuthTag128;
  pub use crate::auth_tag::AuthTag256;
  pub use crate::error::Error;
  pub use crate::error::Result;
  pub use crate::facade::decrypt;
  #[cfg(feature = "rand")]
  pub use crate::facade::encrypt;
  pub use crate::key::Key;
  pub use crate::key::Key128;
  pub use crate::key::Key256;
  pub use crate::newtypes::AssociatedData;
  pub use crate::newtypes::Ciphertext;
  pub use crate::newtypes::CiphertextMut;
  pub use crate::newtypes::Plaintext;
  pub use crate::newtypes::PlaintextMut;
}

/// Low-level APIs that should be used with great care.
///
/// **Prefer using [`easy`] APIs instead.** Using [`careful`] APIs requires
/// cryptographic expertise.
///
/// > You've got to ask yourself one question: 'Do I feel lucky?' Well, do
/// > you, punk?
/// >
/// > — [_Dirty Harry_](https://en.wikipedia.org/wiki/Dirty_Harry_(character))
///
/// See an overview of this module in [the crate
/// docs][crate#the-careful-module].
pub mod careful {
  pub use crate::nonce::Nonce;
  pub use crate::nonce::Nonce128;
  pub use crate::nonce::Nonce256;

  macro_rules! gen_aegis_mod {
    ($algo:ident, $name:literal) => {
      pastey::paste! {
        #[doc = "Implements " $name "."]
        pub mod $algo {
          pub use crate::arch::api::$algo::encrypt_in_place_detached;
          pub use crate::arch::api::$algo::encrypt_to_slice_detached;
          pub use crate::arch::api::$algo::decrypt_in_place_detached;
          pub use crate::arch::api::$algo::decrypt_to_slice_detached;

          crate::facade::gen_aegis_facade_fns!($algo);
        }
      }
    };
  }

  gen_aegis_mod!(aegis128l, "AEGIS-128L");
  gen_aegis_mod!(aegis128x2, "AEGIS-128X2");
  gen_aegis_mod!(aegis128x4, "AEGIS-128X4");
  gen_aegis_mod!(aegis256, "AEGIS-256");
  gen_aegis_mod!(aegis256x2, "AEGIS-256X2");
  gen_aegis_mod!(aegis256x4, "AEGIS-256X4");
}