KCAPI - The Official High-level Rust Bindings for libkcapi

This repository contains the rust sources for the official high-level rust bindings for libkcapi - A userspace interface to the Linux Kernel's Cryptographic API (KCAPI). These bindings are based on top of the kcapi-sys crate which is a submodule of this crate.

Usage

In order to include this crate in your dependencies, include it in your Cargo.toml as follows:

kcapi = "*"

Once this is done, you may access the various modules provided by this crate in your Rust sources:

The major modules provided by this crate are:

• kcapi::md - Provides message digest capabilities
• kcapi::skcipher - Provides symmetric key ciphers
• kcapi::aead - Provides Authenticated Encryption with Associated Data (AEAD) Ciphers
• kcapi::rng - Provides Random Number Generation support.
• kcapi::akcipher - Provides Asymmetric key ciphers.
• kcapi::kdf - Provides Key-Derivation Function (KDF) support.

A simple example for using the convenience hash API is given below:

fn main() {
    let input = "This is a test string to be hashed!".as_bytes().to_vec();
    let digest = match kcapi::md::digest(
        "sha1"  // The algorithm to be used for the digest (from /proc/crypto)
        input,  // The input to be digested
    ) {
        Ok(digest) => digest,
        Err(e) => panic!("{}", e),
    }

    println!("{}", hex::encode(digest));
}

Each API provided will return a KcapiResult typed Result enum. On error, a KcapiError will be returned which has the following structure:

struct KcapiError {
    code: i64,          // The Error code (generally errno style)
    message: String     // The error message which can be printed
}

Build and Test

This section describes how the kcapi crate can be built and tested locally.

Kernel Configuration

This crate requires the Linux Kernel to be compiled with the following options:

• CONFIG_CRYPTO_USER=m - Compile the af_alg.ko module.
• CONFIG_CRYPTO_USER_API=y - Enable Userland crypto API.
• CONFIG_CRYPTO_USER_API_HASH=y - Enable the hash API.
• CONFIG_CRYPTO_USER_API_SKCIPHER=y - Enable the Symmetric cipher API.
• CONFIG_CRYPTO_USER_API_RNG=y - Enable the RNG API.
• CONFIG_CRYPTO_USER_API_AEAD=y - Enable the AEAD API.

If you wish to perform Cryptographic Algorithm Validation Program (CAVP) testing on the RNG, then you must also enable the following option.

• CONFIG_CRYPTO_USER_API_RNG_CAVP=y - Enable RNG CAVP testing from userland.

After the patches in the kernel-patches directory of this crate are applied, the following config option can also be enabled:

• CONFIG_CRYPTO_USER_API_AKCIPHER=y - Enable the Asymmetric cipher API.

Once these configuration options are enabled in the Linux Kernel, and the compilation succeeds, you may use this crate to it's full potential.

Pre-requisites

In order to build this project, it must be checked out along with all of it's submodules recursively:

git clone https://github.com/puru1761/kcapi.git --recurse-submodules

Install all build dependencies. These are:

• autotools
• autoconf
• llvm-dev

RPM based packages

sudo yum install automake autoconf llvm-devel

Debian based packages

sudo apt-get install autotools-dev autoconf llvm-dev

If LLVM_CONFIG_PATH is not set, then set it with:

export LLVM_CONFIG_PATH="/path/to/llvm-config"

Build

We use cargo as our build system for building this crate. Build it using:

cargo build

Test

We have a few sanity tests written to make sure that the bindings work as expected. Run these tests using:

cargo test

All of these tests are defined in src/test/test_*.rs. Developers are welcome to write more tests here in order to ensure that our code quality is the best.

Author

• Purushottam A. Kulkarni <puruk@protonmail.com>