SymCrypt Rust Wrapper

This crate provides friendly and idiomatic Rust wrappers over SymCrypt, an open-source cryptographic library.

This crate has a dependency on symcrypt-sys, which utilizes bindgen to create Rust/C FFI bindings.

Note: As of version 0.2.0, only Windows AMD64, and Azure Linux are fully supported, with partial support for other Linux distros such as Ubuntu.

Quick Start Guide

Windows:

Download the symcrypt.dll and symcrypt.lib for you corresponding CPU architecture from the SymCrypt Releases Page and place them somewhere accessible on your machine.

Set the required SYMCRYPT_LIB_PATH environment variable. You can do this by using the following command:

setx SYMCRYPT_LIB_PATH "<your-path-to-symcrypt-lib-folder>"

During runtime, Windows will handle finding all needed dll's in order to run the intended program, this includes our symcrypt.dll file.

Here are 2 recommended options to ensure your symcrypt.dll is found by Windows during runtime, for more info please see Dynamic-link library search order.

1. Put the symcrypt.dll in the same folder as your output .exe file. If you are doing development (not release), the common path will be: C:\your-project\target\debug\.
2. Permanently add the symcrypt.dll path into your System PATH environment variable. Doing this will ensure that any project that uses the SymCrypt crate will be able to access symcrypt.lib

For more information please see the INSTALL.md file on the rust-symcrypt page

Linux:

Download and all of the libsymcrypt.so* files for you corresponding CPU architecture from the SymCrypt Releases Page.

Support for Debian and Ubuntu via package manager is in the works, for now you must place the libsymcrypt.so* files into linker load path. The way that this is set will vary between distros. On most distros it set via the environment variable $LD_LIBRARY_PATH.

Package manager support is already available if you are using Azure Linux via tdnf install symcrypt.

For more information please see the INSTALL.md file on the rust-symcrypt page

Note: This path may be different depending on your flavour of Linux. The goal is to place the libsymcrypt.so* files in a location where the your Linux distro can find the required libs at build/run time.

Supported APIs

Hashing:

• Sha256 ( statefull/stateless )
• Sha384 ( statefull/stateless )

HMAC:

• HmacSha256 ( statefull/stateless )
• HmacSha384 ( statefull/stateless )

GCM:

• Encryption ( in place )
• Decryption ( in place )

ChaCha:

• Encryption ( in place )
• Decryption ( in place )

ECDH:

• ECDH Secret Agreement

Usage

There are unit tests attached to each file that show how to use each function. Included is some sample code to do a stateless Sha256 hash. symcrypt_init() must be run before any other calls to the underlying symcrypt code.

Note: This code snippet also uses the hex crate.

Instructions:

add symcrypt to your Cargo.toml file.

[dependencies]
symcrypt = "0.2.0"
hex = "0.4.3"

include symcrypt in your code

use symcrypt::hash::sha256; 
use symcrypt::symcrypt_init();
use hex;
fn main() {
    symcrpyt_init();
    let data = hex::decode("641ec2cf711e").unwrap();
    let expected: &str = "cfdbd6c9acf9842ce04e8e6a0421838f858559cf22d2ea8a38bd07d5e4692233";

    let result = sha256(&data);
    assert_eq!(hex::encode(result), expected);
}