Crate symcrypt

Source
Expand description

§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.

symcrypt version 0.5.1 is based off of SymCrypt v103.4.2.. You must use a version that is greater than or equal to SymCrypt v103.4.2.

To view a detailed list of changes please see the releases page.

§Supported Configurations

Operating EnvironmentArchitectureDynamic Linking
Windows user modeAMD64, ARM64✅
UbuntuAMD64, ARM64✅
Azure Linux 3AMD64, ARM64✅

§Supported APIs

Hashing:

  • Md5 ( stateful/stateless )
  • Sha1 ( stateful/stateless )
  • Sha256 ( stateful/stateless )
  • Sha384 ( stateful/stateless )
  • Sha512 ( stateful/stateless )
  • Sha3_256 ( stateful/stateless )
  • Sha3_384 ( stateful/stateless )
  • Sha3_512 ( stateful/stateless )

HMAC:

  • HmacMd5 ( stateful/stateless )
  • HmacSha1 ( stateful/stateless )
  • HmacSha256 ( stateful/stateless )
  • HmacSha384 ( stateful/stateless )
  • HmacSha512 ( stateful/stateless )

HKDF:

  • HmacMd5
  • HmacSha1
  • HmacSha256
  • HmacSha384
  • HmacSha512

Encryption:

  • AES-GCM Encrypt/Decrypt
  • ChaCha20-Poly1305 Encrypt/Decrypt
  • AES-CBC Encrypt/Decrypt

ECC:

  • ECDH Secret Agreement ( NistP256, NistP384, NistP521, Curve25519)
  • ECDSA Sign / Verify ( NistP256, NistP384, NistP521 )

RSA:

  • PKCS1 ( Sign, Verify, Encrypt, Decrypt )
  • PSS ( Sign, Verify )
  • OAEP ( Encrypt, Decrypt )

Note: Md5 and Sha1, and PKCS1 Encrypt/Decrypt are considered weak crypto, and are only added for interop purposes. To enable either Md5 or Sha1, or Pkcs1 Encrypt/Decrypt pass the md5 or sha1 or pkcs1-encrypt-decrypt flag into your Cargo.toml.

§Quick Start Guide

symcrypt requires the SymCrypt library to be present at both build time and run time.

§Windows:

Download the latest symcrypt.dll and symcrypt.lib for your 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>"

You will need to restart terminal / cmd after setting the environment variable.

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

§Linux:

§Azure Linux 3:

SymCrypt is pre-installed on Azure Linux 3 machines. Please ensure that you have the most up to date version of SymCrypt by updating via tdnf.

§Other distros:

For Ubuntu, you can install SymCrypt via package manager by connecting to PMC.

  1. Connect to PMC
  2. sudo apt-get install symcrypt

Alternatively, you can manually install the lib files:

Download the latest libsymcrypt.so* files for your corresponding CPU architecture from the SymCrypt Releases Page and place them in your machines $LD_LIBRARY_PATH.

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, and architecture. 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.

§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.

Note: This code snippet also uses the hex crate.

§Instructions:

add symcrypt to your Cargo.toml file.

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

include symcrypt in your code

use symcrypt::hash::sha256; 
use hex;

let data = hex::decode("641ec2cf711e").unwrap();
let expected: &str = "cfdbd6c9acf9842ce04e8e6a0421838f858559cf22d2ea8a38bd07d5e4692233";

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

Modules§

chacha
ChaChaPoly1305 Functions. For further documentation please refer to symcrypt.h
cipher
Block Cipher functions related to creating expanded keys. For further information please see symcrypt.h for more info
ecc
ECC functions related to creating an EcKey. For further information please see symcrypt.h for more info
errors
Friendly rust errors for SYMCRYPT_ERROR. For more info on SYMCRYPT_ERRORS please refer to symcrypt.h
gcm
Galois Counter Mode functions. For further documentation please refer to symcrypt.h
hash
Hashing functions. For further documentation please refer to symcrypt.h
hkdf
HKDF functions. For more info please refer to symcrypt.h
hmac
Hmac functions. For further documentation please refer to symcrypt.h
rsa
RSA functions related to creating a RSA Key. For further documentation please refer to symcrypt.h

Enums§

NumberFormat
NumberFormat is an enum that contains a friendly representation of endianess

Functions§

symcrypt_random
Takes in a a buffer called buff and fills it with random bytes. This function cannot fail.