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
// Copyright (c) 2019, Nick Stevens <nick@bitcurry.com>
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/license/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! A library for encrypting and decrypting file streams using libsodium.
//!
//! This library provides a Rust implementation of the saltlick binary file
//! format, which is itself a format for encrypting and decrypting files using
//! strong elliptic curve cryptography. See the [saltlick spec] for details
//! about the motivation and implementation of the file format itself.
//!
//! Both low-level and high-level APIs are provided. The low-level API requires
//! manually updating an encrypter with chunks of plaintext and receiving
//! ciphertext, or updating a decrypter with chunks of ciphertext and receiving
//! plaintext. High-level APIs are provided for Rust's [`Read`], [`BufRead`],
//! and [`Write`] traits.
//!
//! [saltlick spec]: https://github.com/saltlick-crypto/saltlick-spec
//! [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
//! [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
//! [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
//!
//! # Usage
//!
//! First, add this to your Cargo.toml:
//!
//! ```toml
//! [dependencies]
//! saltlick = "0.4"
//! ```
//!
//! Next:
//!
//! ```
//! use saltlick::{
//! read::SaltlickDecrypter,
//! write::SaltlickEncrypter,
//! SaltlickError,
//! };
//! use std::{
//! error::Error,
//! fs::File,
//! io::{self, Cursor, Read, Write},
//! };
//!
//! fn main() -> Result<(), Box<dyn Error>> {
//! // Generate a new public/secret keypair
//! let (public, secret) = saltlick::gen_keypair();
//!
//! // Writing data to a stream
//! let writer = Vec::new();
//! let mut stream = SaltlickEncrypter::new(public.clone(), writer);
//! stream.write_all(b"I have a secret for you")?;
//! let ciphertext = stream.finalize()?;
//!
//! // Reading data back from stream
//! let reader = Cursor::new(ciphertext);
//! let mut stream = SaltlickDecrypter::new(public.clone(), secret.clone(), reader);
//! let mut output = String::new();
//! stream.read_to_string(&mut output)?;
//! assert_eq!("I have a secret for you", output);
//!
//! // Save public and private keys as PEM format
//! let public_pem = public.to_pem();
//! let secret_pem = secret.to_pem();
//!
//! Ok(())
//! }
//! ```
//!
//! # Generating Keys
//!
//! In addition to generating keys programmatically, it is possible to generate
//! compliant key files with OpenSSL 1.1.0 or newer:
//!
//! ```sh
//! openssl genpkey -algorithm x25519 > secret.pem
//! openssl pkey -in secret.pem -pubout > public.pem
//! ```
// Enables the nightly-only doc_cfg feature when the `docsrs` attribute is
// preset. We only set this attribute during builds on docs.rs, configured
// using Cargo.toml package metadata.
#![cfg_attr(docsrs, feature(doc_cfg))]
pub mod bufread;
pub mod crypter;
pub mod read;
pub mod write;
#[cfg(feature = "io-async")]
pub(crate) mod async_;
mod commonio;
mod error;
mod key;
mod state;
mod version;
pub use self::{
error::{SaltlickError, SaltlickKeyIoError},
key::{gen_keypair, PublicKey, SecretKey, PUBLICKEYBYTES, SECRETKEYBYTES},
version::Version,
};
#[cfg(feature = "io-async")]
pub use self::async_::stream;
#[cfg(test)]
mod testutils {
use rand::{RngCore, SeedableRng};
use rand_xorshift::XorShiftRng;
pub(crate) fn random_bytes(seed: u64, size: usize) -> Box<[u8]> {
let mut rng = XorShiftRng::seed_from_u64(seed);
let mut bytes = vec![0u8; size];
rng.fill_bytes(&mut bytes);
bytes.into_boxed_slice()
}
}