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 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
//! Rust bindings to the [sodium library](https://github.com/jedisct1/libsodium). //! //! Sodium is a portable implementation of Dan Bernsteins [`NaCl`: Networking and //! Cryptography library](http://nacl.cr.yp.to). //! //! For details on building rust_sodium, see //! [the README](https://github.com/maidsafe/rust_sodium/blob/master/README.md). //! //! For most users, if you want public-key (asymmetric) cryptography you should use //! the functions in [`crypto::box_`](crypto/box_/index.html) for encryption/decryption. //! //! If you want secret-key (symmetric) cryptography you should be using the //! functions in [`crypto::secretbox`](crypto/secretbox/index.html) for encryption/decryption. //! //! For public-key signatures you should use the functions in //! [`crypto::sign`](crypto/sign/index.html) for signature creation and verification. //! //! Unless you know what you're doing you most certainly don't want to use the //! functions in [`crypto::scalarmult`](crypto/scalarmult/index.html), //! [`crypto::stream`](crypto/stream/index.html), [`crypto::auth`](crypto/auth/index.html) and //! [`crypto::onetimeauth`](crypto/onetimeauth/index.html). //! //! ## Thread Safety //! All functions in this library are thread-safe provided that the [`init()`](fn.init.html) //! function has been called during program execution. //! //! If [`init()`](fn.init.html) hasn't been called then all functions except the random-number //! generation functions and the key-generation functions are thread-safe. //! //! # Public-key cryptography //! [`crypto::box_`](crypto/box_/index.html) //! //! [`crypto::sign`](crypto/sign/index.html) //! //! # Sealed boxes //! [`crypto::sealedbox`](crypto/sealedbox/index.html) //! //! # Secret-key cryptography //! [`crypto::secretbox`](crypto/secretbox/index.html) //! //! [`crypto::stream`](crypto/stream/index.html) //! //! [`crypto::auth`](crypto/auth/index.html) //! //! [`crypto::onetimeauth`](crypto/onetimeauth/index.html) //! //! # Low-level functions //! [`crypto::hash`](crypto/hash/index.html) //! //! [`crypto::verify`](crypto/verify/index.html) //! //! [`crypto::shorthash`](crypto/shorthash/index.html) #![doc( html_logo_url = "https://raw.githubusercontent.com/maidsafe/QA/master/Images/maidsafe_logo.png", html_favicon_url = "https://maidsafe.net/img/favicon.ico", test(attr(forbid(warnings))) )] // For explanation of lint checks, run `rustc -W help` or see // https://github.com/maidsafe/QA/blob/master/Documentation/Rust%20Lint%20Checks.md #![forbid( bad_style, exceeding_bitshifts, mutable_transmutes, no_mangle_const_items, unknown_crate_types, warnings )] #![deny( deprecated, improper_ctypes, missing_docs, non_shorthand_field_patterns, overflowing_literals, plugin_as_library, stable_features, unconditional_recursion, unknown_lints, unused, unused_allocation, unused_attributes, unused_comparisons, unused_features, unused_parens, while_true )] #![warn( trivial_numeric_casts, unused_extern_crates, unused_import_braces, unused_qualifications, unused_results )] // Allow `trivial_casts` to cast `u8` to `c_char`, which is `u8` or `i8`, depending on the // architecture. #![allow( box_pointers, missing_copy_implementations, missing_debug_implementations, trivial_casts, unsafe_code, variant_size_differences )] #[cfg(test)] extern crate hex; #[cfg(test)] extern crate rmp_serde; #[cfg(test)] extern crate serde_json; #[macro_use] extern crate unwrap; use rust_sodium_sys as ffi; #[macro_use] mod newtype_macros; pub mod randombytes; pub mod utils; pub mod version; #[cfg(test)] mod test_utils; /// Cryptographic functions pub mod crypto { pub mod aead; pub mod auth; pub mod box_; pub mod hash; pub mod kx; pub mod onetimeauth; pub mod pwhash; pub mod scalarmult; pub mod sealedbox; pub mod secretbox; pub mod shorthash; pub mod sign; pub mod stream; pub mod verify; } /// Initialises libsodium and chooses faster versions of the primitives if possible. Also makes the /// random number generation functions (`gen_key`, `gen_keypair`, `gen_nonce`, `randombytes`, /// `randombytes_into`) thread-safe. /// /// `init()` returns `Ok` if initialisation succeeded and `Err` if it failed. pub fn init() -> Result<(), ()> { if unsafe { ffi::sodium_init() } >= 0 { Ok(()) } else { Err(()) } } #[allow(clippy::doc_markdown)] /// Sets [libsodium's `randombytes_implementation`] /// (https://download.libsodium.org/doc/advanced/custom_rng.html) to use a /// [Rust `Rng` implementation](../rand/trait.Rng.html) and initialises libsodium. /// See [the `rust_sodium-sys`' docs](../rust_sodium_sys/fn.init_with_rng.html) for further details. pub fn init_with_rng<T: rand::Rng>(rng: &mut T) -> Result<(), i32> { ffi::init_with_rng(rng) }