win-crypto-ng 0.5.1

Safe bindings to Windows Cryptography API: Next Generation
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
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

# win-crypto-ng


[![crates.io](https://img.shields.io/crates/v/win-crypto-ng.svg)](https://crates.io/crates/win-crypto-ng)
[![docs.rs](https://docs.rs/win-crypto-ng/badge.svg)](https://docs.rs/crate/win-crypto-ng)
![MSRV](https://img.shields.io/badge/rustc-1.60+-blue.svg)
[![Build status](https://github.com/emgre/win-crypto-ng/workflows/CI/badge.svg)](https://github.com/emgre/win-crypto-ng/actions)
[![License](https://img.shields.io/github/license/emgre/win-crypto-ng)](https://github.com/emgre/win-crypto-ng/blob/master/LICENSE.md)

Safe Rust bindings to Microsoft Windows
[Cryptography API : Next Generation (CNG)](https://docs.microsoft.com/en-us/windows/win32/seccng/cng-portal)

CNG are cryptographic primitives and utilities provided by the operating system and/or hardware. It is available since
Windows Vista and replaces the now deprecated
[CryptoAPI](https://docs.microsoft.com/fr-fr/windows/win32/seccrypto/cryptography-portal).

The primitives do **not** depend on OpenSSL or other libraries of the sort, they are provided by Microsoft and/or by
the hardware manufacturer. They are the primitives used in kernel space programs. Therefore, if you are using Microsoft
Windows, you already accepted to trust these primitives.

## CNG Features


- Validated by FIPS 140-2 and part of the Target of Evaluation for the Windows Common Criteria certification
- Full support for NSA Suite B algorithms
- Kernel support (not through the Rust bindings)
- Auditing in the key storage provider (KSP)
- Thread safe

## Supported features in Rust

- Asymmetric encryption (RSA)
- Digital signatures
  - Supported algorithms: RSA, DSA, ECDSA.
- Key exchange
  - Supported algorithms: DH, ECDH.
- Symmetric encryption
  - Supported algorithms: AES, DES, DES-X, RC2, 3DES, 3DES-112.
  - Supported chaining modes: ECB, CBC, CFB.
- Hash functions
  - Supported algorithms: SHA-1, SHA-256, SHA-384, SHA-512, MD2, MD4, MD5.
- Cryptographically secure random number generation

*More to come*

## Cargo features


- `zeroize` - Uses `zeroize` crate to zero intermediate buffers on destruction
- `rand` - Implements `rand` crate traits for the CNG-provided CSPRNG
  (cryptographically secure pseudorandom number generator)
- `block-cipher` - Implements `block-cipher` traits for CNG block ciphers.

By default, only the `zeroize` feature is enabled.

## Examples


### Asymmetric encryption (RSA)


```rust
use win_crypto_ng::asymmetric::{AsymmetricKey, EncryptionPadding, Rsa};
let key = AsymmetricKey::builder(Rsa).key_bits(1024).build().unwrap();

let plaintext = b"This is an important message.";

let padding = Some(EncryptionPadding::Pkcs1);
let ciphertext = key.encrypt(padding.clone(), &*plaintext).unwrap();
assert_eq!(ciphertext.len(), 1024 / 8);
let decoded = key.decrypt(padding, ciphertext.as_ref()).unwrap();
assert_eq!(plaintext, decoded.as_ref());
```

### Digital signatures

```rust
use win_crypto_ng::asymmetric::signature::{Signer, Verifier, SignaturePadding};
use win_crypto_ng::asymmetric::{AsymmetricKey, Rsa};
use win_crypto_ng::hash::HashAlgorithmId;

let key = AsymmetricKey::builder(Rsa).key_bits(1024).build().unwrap();

let data: Vec<u8> = (0..32).collect();
let padding = SignaturePadding::pkcs1(HashAlgorithmId::Sha256);
let signature = key.sign(&*data, Some(padding)).expect("Signing to succeed");

key.verify(&data, &signature, Some(padding)).expect("Signature to be valid");

key.verify(&[0xDE, 0xAD], &signature, Some(padding)).expect_err("Bad digest");
key.verify(&data, &[0xDE, 0xAD], Some(padding)).expect_err("Bad signature");
```

### Symmetric encryption


```rust
use win_crypto_ng::symmetric::{ChainingMode, SymmetricAlgorithm, SymmetricAlgorithmId, Padding};

const KEY: &'static str = "0123456789ABCDEF";
const IV: &'static str = "asdfqwerasdfqwer";
const DATA: &'static str = "This is a test.";

let iv = IV.as_bytes().to_vec();

let algo = SymmetricAlgorithm::open(SymmetricAlgorithmId::Aes, ChainingMode::Cbc).unwrap();
let key = algo.new_key(KEY.as_bytes()).unwrap();
let ciphertext = key.encrypt(Some(&mut iv.clone()), DATA.as_bytes(), Some(Padding::Block)).unwrap();
let plaintext = key.decrypt(Some(&mut iv.clone()), ciphertext.as_slice(), Some(Padding::Block)).unwrap();

assert_eq!(std::str::from_utf8(&plaintext.as_slice()[..DATA.len()]).unwrap(), DATA);
```

### Hash functions


```rust
use win_crypto_ng::hash::{HashAlgorithm, HashAlgorithmId};

const DATA: &'static str = "This is a test.";

let algo = HashAlgorithm::open(HashAlgorithmId::Sha256).unwrap();
let mut hash = algo.new_hash().unwrap();
hash.hash(DATA.as_bytes()).unwrap();
let result = hash.finish().unwrap();

assert_eq!(result.as_slice(), &[
    0xA8, 0xA2, 0xF6, 0xEB, 0xE2, 0x86, 0x69, 0x7C,
    0x52, 0x7E, 0xB3, 0x5A, 0x58, 0xB5, 0x53, 0x95,
    0x32, 0xE9, 0xB3, 0xAE, 0x3B, 0x64, 0xD4, 0xEB,
    0x0A, 0x46, 0xFB, 0x65, 0x7B, 0x41, 0x56, 0x2C,
]);
```

### Cryptographically secure random number generator


```rust
use win_crypto_ng::random::{RandomAlgorithmId, RandomNumberGenerator};

let mut buffer = [0u8; 32];
let rng = RandomNumberGenerator::system_preferred();
rng.gen_random(&mut buffer).unwrap();

assert_ne!(&buffer, &[0u8; 32]);
```

## License


Licensed under the 3-Clause BSD License. See [LICENSE.md](LICENSE.md) for more details.

Copyright (c) 2019-2020 Émile Grégoire. All rights reserved.