Skip to content

docs: Improve and add documentation for OCICRYPT_CONFIG for pkcs11 su… #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stefanberger merged 1 commit into from
Jul 30, 2026
Merged

docs: Improve and add documentation for OCICRYPT_CONFIG for pkcs11 su… #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions config/pkcs11config/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,15 @@ const ENVVARNAME = "OCICRYPT_CONFIG"
// parseConfigFile parses a configuration file; it is not an error if the configuration file does
// not exist, so no error is returned.
// A config file may look like this:
// module-directories:
// - /usr/lib64/pkcs11/
// - /usr/lib/pkcs11/
// allowed-module-paths:
// - /usr/lib64/pkcs11/
// - /usr/lib/pkcs11/
/*
pkcs11:
module-directories:
- /usr/lib64/pkcs11/
- /usr/lib/pkcs11/
allowed-module-paths:
- /usr/lib64/pkcs11/
- /usr/lib/pkcs11/
*/
func parseConfigFile(filename string) (*OcicryptConfig, error) {
// a non-existent config file is not an error
_, err := os.Stat(filename)
Expand Down
30 changes: 29 additions & 1 deletion docs/pkcs11.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,38 @@

Ocicrypt supports the use of an experimental pkcs11-based protocol. This allows the ability to encrypt a container image so that it can be decrypted by a key which resides in a Hardware Security Module (HSM). In this document, we will go through a tutorial on how to setup and use this capability with a software emulated HSM, SoftHSM. See [this guide](https://github.com/containers/ocicrypt/blob/main/docs/cex-ep11.md) on how to do this with an IBM CryptoExpress HSM instead.

This tutorial is done on Ubuntu.
# The OCICRYPT_CONFIG environment variable

The `OCICRYPT_CONFIG` environment variable can be used to configure the pkcs11
module support and allows a user to define the module-directories where pkcs11
modules can be found as well as set restrictions for which pkcs11 modules can
be used. For a default configuration supporting various distros' pkcs11 module
paths, this enviroment variable can be set to the value `internal`. Otherwise
it should be assigned the name of a file. The following is an example of the
contents of such a file:

```
pkcs11:
module-directories:
- /usr/lib64/pkcs11/
- /usr/lib/pkcs11/
- /usr/lib/softhsm/
allowed-module-paths:
- /usr/lib64/pkcs11/libsofthsm2.so
- /usr/lib/pkcs11/libsofthsm2.so
- /usr/lib/softhsm/libsofthsm2.so
```

The above configuration file defines 3 different paths for the
module-directories covering the possible paths for various Linux distributions
where SoftHSM's pkcs11 module can be found. Since the allowed-module-paths
explicitly mention the libsofthsm2.so pkcs11 module, the resulting policy
only allows usage of SoftHSM's pkcs11 module.

# Setting up SoftHSM

The following tutorial is done on Ubuntu.

## Requirements

On top of the generic ocicrypt requirements, install the following packages:
Expand Down
Loading