libkcapi - Linux Kernel Crypto API User Space Interface Library

The Linux kernel exports a Netlink interface of type AF_ALG to allow user space to utilize the kernel crypto API.

libkcapi uses this Netlink interface and exports easy to use APIs so that a developer does not need to consider the low-level Netlink interface handling.

The library does not implement any cipher algorithms. All consumer requests are sent to the kernel for processing. Results from the kernel crypto API are returned to the consumer via the library API.

The kernel interface and therefore this library can be used by unprivileged processes.

The focus during the development of this library is put on speed. This library does not perform any memcpy for processing the cryptographic data! The library uses scatter / gather lists to eliminate the need for moving data around in memory.

GitHub Link

A public git repository is found at smuellerDD/libkcapi.

API Documentation

A full documentation is derived from the source code comments in kcapi-kernel-if.c.

See the README file enclosed in the source code for details on how to use the code.

See the TODO file enclosed in the source code for details on open items.

Source Code

The following source code contains the implementation of libkcapi.

Link Changes

libkcapi-0.1.0

Signature

Initial version

libkcapi-0.2.0

Signature

Changes 0.2.0:
  • Add kcapi_aead_[enc|dec]_* calls for non-aligned requests
  • Updated kernel patch to match what has been sent to LKML
  • Documentation of API calls and data structures completed
  • Add kcapi_md_digestsize
  • Add sanity checking to IV setting API
  • Add kcapi_pad_iv
  • Add sanity check around getsockopt wrapper API call
  • API documentation marks input / output parameters
  • API documentation explains AEAD decryption EBADMSG error code
  • Update of teets to cover all changed / new API calls

libkcapi-0.2.1

Signature

Changes 0.2.1:
  • Add automation to generate nicely formatted guidance documents out of source code comments. See README.md for make targets generating the respective guidance documents.

libkcapi-0.3.0

Signature

Changes 0.3.0:
  • new kernel patch for AEAD/RNG interface
  • Support for updated AEAD kernel interface
  • Use of NETLINK_CRYPTO instead of getsockopt (code currently disabled due to a bug in crypto/crypto_user.c -- see TODO)

libkcapi-0.4.0

Signature

Changes 0.4.0:
  • update AEAD cipher interface for current implemetation
  • remove nonalinged API
  • add one-shot and stream API
  • use zero copy interface for one-shot APi
  • add tests to cover one-shot and stream API
  • full documentation update
  • stress testing the library and the AEAD/RNG implementation

libkcapi-0.5.0

Signature

Changes 0.5.0:
  • kernel interface for AEAD and RNG changed
  • add kcapi_rng_seed API call

libkcapi-0.6.1

Signature

Changes 0.6.1:
  • add kcapi_md_blocksize
  • add stress / negative testing
  • add hint to NETLINK_CRYPTO patch requirement

libkcapi-0.6.2

Signature

Changes 0.6.2:
  • update all vmsplice invocations to consider the limitations of the pipe buffer of 16 pages (the limitation in the kernel is enforced by vmsplice_to_pipe setting nr_pages_max and splice_from_pipe_feed which iterates over the available pipe->nrbufs) - this fixes message digests and symmetric operations for input data larger than 16 pages; the AEAD cipher contains a sanity check that the input data size is not too large -- thanks to Amit Uttamchandani for the bug report
  • update aead/rng kernel pages to match 3.19-rc1

libkcapi-0.6.3

Signature

Changes 0.6.3:
  • Remove several sanity checks in the API functions. This shall allow the invocation of edge conditions (like no plaintext, but AAD and tag). The kernel contains the appropriate sanity checks too. Therefore there is no harm in removing them.
  • Add testing of long AAD: fill 16 pages with 65504 bytes AAD and 32 bytes plaintext (stream API) and 15 pages AAD plus 16th page holding plaintext (one-shot API).
  • Update AEAD interface to allow arbitrary AAD sizes.

libkcapi-0.6.4

Signature

Changes 0.6.4:
  • Update AEAD interface patch
  • Add new test invoking cipher instance multiple times (-d flag of test application)

libkcapi-0.6.5

Signature

Changes 0.6.5:
  • Measuring speed of vmsplice vs sendmsg interfaces and added heuristic to select the fastest implementation
  • Enhance documentation to explain usage of API better
  • added speed measuring tests in speed-test/
  • return errno for all syscalls through the API return codes for better error handling
  • process kernel flag of MSG_TRUNG for AEAD ciphers

libkcapi-0.7.0

Signature

Changes 0.7.0:
  • AEAD kernel part does not relay MSG_TRUNC any more, thus using the read syscall is more efficient
  • remove kcapi_cipher_setiv and add an IV parameter to all necessary API calls. This prevents the requirement for a function call and requiring the caller to maintain the IV buffer
  • add vmsplice tests to test framework to make sure vmsplice is really executed
  • fix documentation style
  • allow caller to specify which kernel interface (sendmsg / vmsplice) is used for one-shot API calls. This implies extension of one-shot API calls
  • Update stream API tests for AEAD to use 16 IOVECs to test the latest installment of the recvmsg interface of algif_aead

libkcapi-0.7.1

Signature

Changes 0.7.1:
  • AEAD kernel interface is now upstreamed, reference the patches in the documentation appropriately and remove the patches from the kernel patch tree.
  • Test: add rfc4106(gcm(aes)) tests to general test and to speed test
  • Speed test: invoke the ciphers 10 times before time measurement to prime the caches.

libkcapi-0.7.2

Signature

Changes 0.7.2:
  • Move the library code into the directory lib/
  • Fix issues reported by cppcheck
  • AEAD: allow encrypt/decrypt invocations with NULL AAD and NULL PT/CT
  • AEAD: add test for NULL AAD and NULL PT/CT
  • RNG: always invoke seeding operation, even when seed is NULL

libkcapi-0.8.0

Signature

Changes 0.8.0:
  • Fix test.sh to invoke large AEAD test
  • All kcapi_*_destroy functions are void now
  • Update AEAD code to new kernel interface and update the AEAD API
  • Simplify the code for AEAD
  • Add and use kcapi_memset_secure
  • Add AIO logic - but disable it for now
  • Add drop in replacements for sha1sum, sha224sum, sha256sum, sha384sum, sha512sum and md5sum, fipscheck/fipshmac, hmaccalc
  • Remove the kernel-patch/ directory as its code is not consistent with the library any more. Use the current cryptodev-2.6 tree from Herbert Xu.

libkcapi-0.9.0

Signature

Changes 0.9.0:
  • Addition of asymmetric API.

libkcapi-0.10.0

Signature

Changes 0.10.0:
  • simplify kcapi_aead_encrypt and kcapi_aead_decrypt
  • comment out message truncation check
  • test.sh: fix RFC4106 IV handling for kernels >= 4.2 due to overhaul of AEAD support in the kernel
  • use zero-copy in stream operation if possible
  • Add set_pubkey API call
  • convert entire API to use data types with known sizes (i.e. stdint.h)
  • Add asymmetric tests to test.sh
  • Add asymmetric stream cipher API
  • update documentation to cover akcipher API
  • Addition of asymmetric API.

libkcapi-0.10.1

Signature

Changes 0.10.1:
  • Fix issues with the vmsplice usage in stream mode
  • Fix issues with the vmsplice usage in chunk mode
  • Any modification on the tfmfd must be performed before the accept() call as mandated by the update to kernel 4.4.
  • Add support for processing of arbitrary sized symmetric cipher input

libkcapi-0.10.2

Signature

Changes 0.10.2:
  • Fix kernel netlink parsing error message
  • doc: add hint for setting keys before sending data
  • fix compiler warnings about unsigned / signed comparisons

libkcapi-0.11.0

Signature

Changes 0.11.0:
  • Convert all libkcapi data structures into opaque structures. This implies that the *_init functions require a reference to a pointer as these init functions now allocate the struct kcapi_handle data structure.
  • Add clean and consistent logging logic
  • fixed execution when CONFIG_CRYPTO_FIPS is disabled in kernel
  • mark all symbols except API as hidden
  • performance measurements for kcapi_md_updatn added
  • update speed tests for newer AVX/AVX2 kernel handling
  • update documentation to mark all parameters as [in] or [out]

libkcapi-0.11.1

Signature

Changes 0.11.1:
  • move version information to kcapi.h to allow compile time tests for wrapping applications
  • fix error code path mem leaks in _kcapi_handle_init reported by cppcheck

2016-08-02 smueller at chronox.de