yaca/
lib.rs

1/*
2 *  Copyright (c) 2020 Samsung Electronics Co., Ltd All Rights Reserved
3 *
4 *  Contact: Lukasz Pawelczyk <l.pawelczyk@samsung.com>
5 *
6 *  Licensed under the Apache License, Version 2.0 (the "License");
7 *  you may not use this file except in compliance with the License.
8 *  You may obtain a copy of the License at
9 *
10 *      http://www.apache.org/licenses/LICENSE-2.0
11 *
12 *  Unless required by applicable law or agreed to in writing, software
13 *  distributed under the License is distributed on an "AS IS" BASIS,
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 *  See the License for the specific language governing permissions and
16 *  limitations under the License
17 */
18
19#![doc(test(no_crate_inject))]
20//! YACA - Yet Another Crypto API. Bindings for C library YACA
21//!
22//! # Examples
23//!
24//! ```
25//!use std::ffi::CString;
26//!use yaca::{self, prelude::*};
27//!use yaca::{Key, KeyType, KeyLength, KeyFormat, KeyFileFormat, EncryptContext,
28//!           DecryptContext, EncryptAlgorithm, BlockCipherMode, Padding};
29//!
30//!pub const MSG: &[u8] = b"Lorem ipsum dolor sit amet.";
31//!
32//!fn main() -> Result<(), Box<dyn std::error::Error>>
33//!{
34//!    // Start
35//!
36//!    yaca::initialize()?;
37//!
38//!    // Key generate/export/import example:
39//!
40//!    let key = Key::generate(&KeyType::RsaPrivate,
41//!                            &KeyLength::Bits(512))?;
42//!    let p = CString::new("password")?;
43//!    let data = key.export(&KeyFormat::Default, &KeyFileFormat::Pem, Some(&p))?;
44//!    let key = Key::import(&data, &KeyType::RsaPrivate, Some(&p))?;
45//!
46//!    println!("{:?}: {:?}", key.get_type()?, key.get_length()?);
47//!
48//!    // Encrypt/decrypt example:
49//!
50//!    // Prepare
51//!
52//!    let algo = EncryptAlgorithm::Aes;
53//!    let cbc = BlockCipherMode::Cbc;
54//!    let key_len = KeyLength::Bits(256);
55//!    let sym_key = Key::generate(&KeyType::Symmetric, &key_len)?;
56//!    let iv_len = EncryptContext::get_iv_length(&algo, &cbc, &key_len)?;
57//!    let iv = match &iv_len {
58//!        None => None,
59//!        Some(x) => Some(Key::generate(&KeyType::Iv, x)?),
60//!    };
61//!    if let Some(x) = &iv {
62//!        println!("IV_used: {:?}: {:?}", x.get_type()?, x.get_length()?);
63//!    };
64//!
65//!    // Encrypt
66//!
67//!    let ctx = EncryptContext::initialize(&algo, &cbc, &sym_key, iv.as_ref())?;
68//!    ctx.set_property_padding(&Padding::Pkcs7)?;
69//!    let mut cipher: Vec<u8> = Vec::new();
70//!    for i in MSG.chunks(5) {
71//!        cipher.append(&mut ctx.update(i)?);
72//!    };
73//!    cipher.append(&mut ctx.finalize()?);
74//!
75//!    // Decrypt
76//!
77//!    let ctx = DecryptContext::initialize(&algo, &cbc, &sym_key, iv.as_ref())?;
78//!    ctx.set_property_padding(&Padding::Pkcs7)?;
79//!    let mut plain: Vec<u8> = Vec::new();
80//!    for i in cipher.chunks(5) {
81//!        plain.append(&mut ctx.update(i)?);
82//!    };
83//!    plain.append(&mut ctx.finalize()?);
84//!
85//!    // Check
86//!
87//!    assert_eq!(MSG, plain);
88//!    let plain = CString::new(plain)?;
89//!    println!("{}", plain.to_str()?);
90//!
91//!    // Finish
92//!
93//!    Ok(yaca::cleanup())
94//!}
95//! ```
96//!
97//! # Simple API:
98//!
99//! Defined by functions named `Yaca::simple_*`
100//!
101//! Design constraints:
102//! - All operations are single-shot (no streaming possible)
103//! - Context is not used
104//! - Only digest, signatures and symmetric ciphers are supported
105//! - Disabling PKCS#7 padding for ECB and CBC chaining is not supported
106//! - Changing the default PKCS#1 padding for sign/verify is not supported
107//! - GCM and CCM chaining is not supported
108//! - RC2 effective key bits property is not supported
109//!
110//! ```
111//!use std::ffi::CString;
112//!use yaca::{self, prelude::*};
113//!use yaca::{Key, KeyType, KeyLength, EncryptAlgorithm, BlockCipherMode};
114//!
115//!pub const MSG: &[u8] = b"Lorem ipsum dolor sit amet.";
116//!
117//!fn main() -> Result<(), Box<dyn std::error::Error>>
118//!{
119//!    // Start
120//!    yaca::initialize()?;
121//!
122//!    // Simple encrypt/decrypt of empty data
123//!    let sym_key = Key::generate(&KeyType::Symmetric, &KeyLength::Bits(256))?;
124//!    let v = yaca::simple_encrypt(&EncryptAlgorithm::UnsafeRc4, &BlockCipherMode::None,
125//!                                 &sym_key, None, &Vec::new())?;
126//!    assert!(v.is_empty());
127//!    let v = yaca::simple_decrypt(&EncryptAlgorithm::UnsafeRc4, &BlockCipherMode::None,
128//!                                 &sym_key, None, &Vec::new())?;
129//!    assert!(v.is_empty());
130//!
131//!    // Simple encrypt/decrypt
132//!    let iv = Key::generate(&KeyType::Iv, &KeyLength::Bits(128))?;
133//!    let cipher = yaca::simple_encrypt(&EncryptAlgorithm::Aes, &BlockCipherMode::Cbc,
134//!                                      &sym_key, Some(&iv), MSG)?;
135//!    let plain = yaca::simple_decrypt(&EncryptAlgorithm::Aes, &BlockCipherMode::Cbc,
136//!                                     &sym_key, Some(&iv), &cipher)?;
137//!
138//!    // Check for simple
139//!    assert_eq!(MSG, plain);
140//!    let plain = CString::new(plain)?;
141//!    println!("{}", plain.to_str()?);
142//!
143//!    // Finish
144//!    Ok(yaca::cleanup())
145//!}
146//! ```
147
148
149mod yaca_common;
150mod yaca_lib;
151mod yaca_conv;
152
153mod error;
154mod types;
155mod crypto;
156mod simple;
157mod rsa;
158mod key;
159mod digest;
160mod encrypt;
161mod seal;
162mod sign;
163
164
165/// Include this prelude with `use yaca::prelude::*` to access required traits.
166pub mod prelude {
167    pub use super::crypto::ContextWithPadding;
168    pub use super::crypto::ContextWithRc2Supported;
169    pub use super::crypto::ContextWithXcmEncryptProperties;
170    pub use super::crypto::ContextWithXcmDecryptProperties;
171}
172
173// TODO: consider simplifying those "pub use" in the future
174
175pub type Result<T> = std::result::Result<T, Error>;
176
177pub use error::Error;
178
179pub use types::KeyFormat;
180pub use types::KeyFileFormat;
181pub use types::KeyType;
182pub use types::KeyLength;
183pub use types::KeyLengthEc::{self, *};
184pub use types::KeyLengthDh::{self, *};
185pub use types::DigestAlgorithm;
186pub use types::EncryptAlgorithm;
187pub use types::BlockCipherMode;
188pub use types::Padding;
189pub use types::Kdf;
190
191pub use crypto::initialize;
192pub use crypto::cleanup;
193pub use crypto::memcmp;
194pub use crypto::random_bytes;
195#[doc(inline)]
196pub use prelude::*;  // context traits from crypto
197
198pub use simple::simple_encrypt;
199pub use simple::simple_decrypt;
200pub use simple::simple_calculate_digest;
201pub use simple::simple_calculate_signature;
202pub use simple::simple_verify_signature;
203pub use simple::simple_calculate_cmac;
204pub use simple::simple_calculate_hmac;
205
206pub use rsa::rsa_public_encrypt;
207pub use rsa::rsa_private_decrypt;
208pub use rsa::rsa_private_encrypt;
209pub use rsa::rsa_public_decrypt;
210
211pub use key::Key;
212pub use digest::DigestContext;
213pub use encrypt::EncryptContext;
214pub use encrypt::DecryptContext;
215pub use seal::SealContext;
216pub use seal::OpenContext;
217pub use sign::SignContext;
218pub use sign::VerifyContext;
yaca/lib.rs

yaca/
lib.rs
