Crate kcapi

Source
Expand description

§kcapi - The Official High-level Rust Bindings for libkcapi

This crate provides the official high-level Rust bindings for libkcapi. The goal of this crate is to provide a rusty API to the C library libkcapi, which itself provides consumers the capability to access the Linux Kernel’s Cryptographic API (KCAPI) from userland to perform cryptographic requests.

This is a permissively (BSD-3-Clause) licensed crate which can be included in your applications to remove dependence on OpenSSL or other cryptographic libraries, and use the Linux KCAPI instead.

§Layout

This crate is divided into the following modules:

  • md - Message digest API.
  • skcipher - Symmetric key cipher API.
  • aead - Authenticated Encryption with Associated Data (AEAD) API.
  • rng - Random Number Generation (RNG) API.
  • akcipher - Asymmetric key cipher API.
  • kdf - Key Derivation Function API.

Each of these modules specify their own unique context type. For instance, the skcipher module provides the KcapiSKCipher context type, which can be used to perform encryption/decryption and other operations.

This crate defines a KcapiResult type which can be used to encapsulate output from any consumers of this API, and also propagate errors to callers.

This crate also defines a custom error type KcapiError which implements the fmt::Display trait.

This crate also provides the IOVec type, which can be used to represent a Linux Kernel Scatter/Gather list of u8s.

§Pre-requisites

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.

Modules§

aead
Authenticated Encryption with Associated Data (AEAD) using the Kernel Crypto API (KCAPI)
akcipher
Asymmetric Key Ciphers (akcipher) using the Kernel Crypto API
kdf
Key Derivation Functions (kdf) using the Kernel Crypto API (KCAPI)
md
Message Digest (md) using the Kernel Crypto API (KCAPI)
rng
Random Number Generation (rng) using the Kernel Crypto API (KCAPI)
skcipher
Symmetric Key Ciphers (skcipher) using the Kernel Crypto API (KCAPI)
util
Generic Utilities

Structs§

IOVec
The IOVec type
KcapiError
The KcapiError Type

Constants§

ACCESS_HEURISTIC
Fastest kernel access using internal heuristics.
ACCESS_SENDMSG
Linux Kernel sendmsg(2) API access. See man 2 sendmsg.
ACCESS_VMSPLICE
Linux Kernel VMSplice Access
INIT_AIO
Use Kernel Asynchronous I/O interface if it is available.

Traits§

IOVecTrait
VMSplice

Type Aliases§

KcapiResult
The KcapiResult<T> Type