vendor/orion/src/lib.rs

   1 // MIT License
   2
   3 // Copyright (c) 2018-2022 The orion Developers
   4
   5 // Permission is hereby granted, free of charge, to any person obtaining a copy
   6 // of this software and associated documentation files (the "Software"), to deal
   7 // in the Software without restriction, including without limitation the rights
   8 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 // copies of the Software, and to permit persons to whom the Software is
  10 // furnished to do so, subject to the following conditions:
  11
  12 // The above copyright notice and this permission notice shall be included in
  13 // all copies or substantial portions of the Software.
  14
  15 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  21 // SOFTWARE.
  22
  23 //! A usable pure-Rust cryptography library.
  24 //!
  25 //! ## Authenticated secret-key encryption
  26 //! [`orion::aead`] offers authenticated secret-key encryption using
  27 //! XChaCha20Poly1305.
  28 //!
  29 //! ## Password hashing and verification
  30 //! [`orion::pwhash`] offers password hashing and verification using Argon2i.
  31 //!
  32 //! ## Key derivation
  33 //! [`orion::kdf`] offers key derivation using Argon2i.
  34 //!
  35 //! ## Message authentication
  36 //! [`orion::auth`] offers message authentication and verification using BLAKE2b.
  37 //!
  38 //! ## Hashing
  39 //! [`orion::hash`] offers hashing using BLAKE2b.
  40 //!
  41 //! ## Key exchange
  42 //! [`orion::kex`] offers ephemeral key exchange using X25519 and BLAKE2b.
  43 //!
  44 //! ### A note on `no_std`:
  45 //! When Orion is used in a `no_std` context, the high-level API is not available, since it relies on access to the systems random number generator.
  46 //!
  47 //! More information about Orion is available in the [wiki].
  48 //!
  49 //! [`orion::aead`]: crate::aead
  50 //! [`orion::pwhash`]: crate::pwhash
  51 //! [`orion::kdf`]: crate::kdf
  52 //! [`orion::auth`]: crate::auth
  53 //! [`orion::hash`]: crate::hash
  54 //! [`orion::kex`]: crate::kex
  55 //! [wiki]: https://github.com/orion-rs/orion/wiki
  56
  57 #![cfg_attr(not(feature = "safe_api"), no_std)]
  58 #![forbid(unsafe_code)]
  59 #![deny(clippy::mem_forget)]
  60 #![warn(
  61     missing_docs,
  62     rust_2018_idioms,
  63     trivial_casts,
  64     unused_qualifications,
  65     overflowing_literals
  66 )]
  67 #![doc(html_root_url = "https://docs.rs/orion/0.17.3")]
  68 #![cfg_attr(docsrs, feature(doc_cfg))]
  69
  70 #[cfg(test)]
  71 #[cfg(feature = "safe_api")]
  72 extern crate quickcheck;
  73 #[cfg(test)]
  74 #[cfg(feature = "safe_api")]
  75 #[macro_use(quickcheck)]
  76 extern crate quickcheck_macros;
  77
  78 #[cfg(feature = "alloc")]
  79 #[cfg_attr(feature = "alloc", macro_use)]
  80 extern crate alloc;
  81
  82 #[macro_use]
  83 mod typedefs;
  84
  85 #[macro_use]
  86 /// Utilities such as constant-time comparison.
  87 pub mod util;
  88
  89 /// Errors for Orion's cryptographic operations.
  90 pub mod errors;
  91
  92 /// \[__**Caution**__\] Low-level API.
  93 pub mod hazardous;
  94
  95 #[cfg(feature = "safe_api")]
  96 mod high_level;
  97
  98 #[cfg(feature = "safe_api")]
  99 pub use high_level::hash;
 100
 101 #[cfg(feature = "safe_api")]
 102 pub use high_level::aead;
 103
 104 #[cfg(feature = "safe_api")]
 105 pub use high_level::auth;
 106
 107 #[cfg(feature = "safe_api")]
 108 pub use high_level::pwhash;
 109
 110 #[cfg(feature = "safe_api")]
 111 pub use high_level::kdf;
 112
 113 #[cfg(feature = "safe_api")]
 114 pub use high_level::kex;
 115
 116 #[doc(hidden)]
 117 /// Testing framework.
 118 pub mod test_framework;