Beyond Linux® From Scratch (System V Edition) - Version r12.2-543

Chapter 9. General Libraries

keyutils-1.6.3

Introduction to keyutils

Keyutils is a set of utilities for managing the key retention facility in the kernel, which can be used by filesystems, block devices and more to gain and retain the authorization and encryption keys required to perform secure operations.

[Note]

Note

Development versions of BLFS may not build or run some packages properly if LFS or dependencies have been updated since the most recent stable versions of the books.

Package Information

Keyutils Dependencies

Optional

lsb-tools-0.12 (referred by the test suite)

Kernel Configuration

If running the test suite, some tests needs the following kernel features enabled: 

Security options --->
  [*] Enable access key retention support                                 [KEYS]
  [*]   Large payload keys                                            [BIG_KEYS]
  [*]   Diffie-Hellman operations on retained keys           [KEY_DH_OPERATIONS]

-*- Cryptographic API --->                                              [CRYPTO]
  Public-key cryptography --->
    <*/M> RSA (Rivest-Shamir-Adleman)                               [CRYPTO_RSA]
  Hashes, digests, and MACs --->
    <*/M> SHA-1                                                    [CRYPTO_SHA1]
  [*] Asymmetric (public-key cryptographic) key type --->  [ASYMMETRIC_KEY_TYPE]
    <*> Asymmetric public-key crypto algorithm subtype
                                            ...  [ASYMMETRIC_PUBLIC_KEY_SUBTYPE]
    # If not built into the kernel, [SYSTEM_TRUSTED_KEYRING] won't show up;
    # building as a module won't work:
    <*>   X.509 certificate parser                     [X509_CERTIFICATE_PARSER]
  Certificates for signature checking --->
    [*] Provide system-wide ring of trusted keys        [SYSTEM_TRUSTED_KEYRING]
    [*]   Provide a keyring to which extra trustable keys may be added
                                                ...  [SECONDARY_TRUSTED_KEYRING]
    [*] Provide system-wide ring of blacklisted keys  [SYSTEM_BLACKLIST_KEYRING]

Library routines --->
  Crypto library routines --->
    # If not built into the kernel, [BIG_KEYS] won't show up;
    # building as a module won't work:
    <*> ChaCha20-Poly1305 AEAD support (8-byte nonce library version)
                                              ...  [CRYPTO_LIB_CHACHA20POLY1305]

Installation of keyutils

Install keyutils by running the following commands: 

make

Now, as the root user: 

make NO_ARLIB=1 LIBDIR=/usr/lib BINDIR=/usr/bin SBINDIR=/usr/sbin install

The test suite can only run after installing this package. To test the results, issue, as the root user: 

make -k test

If lsb-tools-0.12 is not installed, the test suite will output some lines complaining the lsb_release command not available but it won't affect the test result.

Command Explanations

NO_ARLIB=1: This make flag disables installing the static library.

Configuring keyutils

Config Files

/etc/request-key.conf and /etc/request-key.d/*

Contents

Installed Programs: keyctl, key.dns_resolver, and request-key
Installed Library: libkeyutils.so
Installed Directory: /etc/keyutils, /etc/request-key.d, and /usr/share/keyutils

Short Descriptions

keyctl

controls the key management facility with a variety of subcommands

key.dns_resolver

is invoked by request-key on behalf of the kernel when kernel services (such as NFS, CIFS and AFS) need to perform a hostname lookup and the kernel does not have the key cached. It is not ordinarily intended to be called directly

request-key

is invoked by the kernel when the kernel is asked for a key that it doesn't have immediately available. The kernel creates a temporary key and then calls out to this program to instantiate it. It is not intended to be called directly

libkeyutils.so

contains the keyutils library API instantiation