'\" t
.\"     Title: sbctl.conf
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/20/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "SBCTL\&.CONF" "5" "10/20/2024" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sbctl.conf \- the sbctl configuration file
.SH "SYNOPSIS"
.sp
/etc/sbctl/sbctl\&.conf
.SH "DESCRIPTION"
.sp
The sbctl configuration file is a YAML file\&. It is read on startup if present\&.
.sp
The file can be used for initial setup of a sbctl installation\&.
.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
.sp
The configuration file is currently only read from /etc/sbctl\&. This might change in the future\&.
.SH "OPTIONS"
.PP
\fBkeydir:\fR /path/to/key/dir
.RS 4
Defines the directory where sbctl will look for keys\&.

Default: /var/lib/sbctl/keys
.RE
.PP
\fBguid:\fR /path/to/guid/file
.RS 4
The location of the file that defines the user created GUID\&.

The GUID is used to unique identify the list of certificates stored in the EFI variables\&.

Default: /var/lib/sbctl/GUID
.RE
.PP
\fBfiles_db:\fR /path/to/files/json
.RS 4
The location of the json file storing the files sbctl will sign\&.

Default: /var/lib/sbctl/files\&.json
.RE
.PP
\fBbundles_db:\fR /path/to/bundles/json
.RS 4
The location of the json file storing the bundles sbctl will sign\&.

Default: /var/lib/sbctl/bundles\&.json
.RE
.PP
\fBlandlock:\fR bool
.RS 4
Enable or disable the landlock sandboxing of sbctl\&.

Default: true
.RE
.sp
\fBdb_additions:\fR [ options\&... ] Include additional keys or checksums into the authorization database for Secure Boot\&. These values are synonymous with the flags passed to \fBsbctl enroll\-keys\fR\&. Valid values: microsoft, tpm\-eventlog, firmware\-builtin, custom
.PP
\fBfiles:\fR [ [\fBpath:\fR /path/to/file \fBoutput:\fR /path/to/output ], \&... ]
.RS 4
A list of files sbctl will sign upon setup\&. It will be used to seed the files_db during initial setup\&.
.PP
\fBpath\fR
.RS 4
Absolute path to a file that sbctl should sign\&.
.RE
.PP
\fBoutput\fR
.RS 4
An optional absolute output path for the signed file\&.
.RE
.RE
.PP
\fBkeys:\fR {\fBpk:\fR {\&...}, \fBkek:\fR {\&...}, \fBdb:\fR {\&...}}
.RS 4
A key\-value pair for all the keys in the key hierarchy used for Secure Boot\&. It is used for the initial bootstrap during setup\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
pk
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
kek
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
db
.RE
.RE
.PP
.RS 4
Each of the hierarchies can specify key type and location for the private key and certificate file independent of each other\&. This allows users to keep some keys on different storage mediums depending on needs\&. An example would be to keep the db key as an unencrypted file easily accessible for signing and the PK on a hardware backed enclave to be better secure the key material\&.
.PP
\fBprivkey:\fR /path/to/privatekey/file
.RS 4
Path to the private key\&.

Defaults:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpk:\fR
/var/lib/sbctl/keys/PK/PK\&.key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBkek:\fR
/var/lib/sbctl/keys/KEK/KEK\&.key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdb\fR: /var/lib/sbctl/keys/db/db\&.key
.RE
.RE
.PP
\fBpubkey:\fR /path/to/certificate/file
.RS 4
Path to the public key\&.

Default:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpk:\fR
/var/lib/sbctl/keys/PK/PK\&.pem
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBkek:\fR
/var/lib/sbctl/keys/KEK/KEK\&.pem
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdb\fR: /var/lib/sbctl/keys/db/db\&.pem
.RE
.RE
.PP
\fBtype:\fR file
.RS 4
The type of key used for this signing key\&.

Only the key type of
\fBfile\fR
is currently supported by sbctl\&.

Default: file
.RE
.RE
.SH "EXAMPLE"
.sp
An example of a /etc/sbctl/sbctl\&.conf file with the default values\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-\-
keydir: /var/lib/sbctl/keys
guid: /var/lib/sbctl/GUID
files_db: /var/lib/sbctl/files\&.json
bundles_db: /var/lib/sbctl/bundles\&.json
landlock: true
db_additions:
\- microsoft
files:
\- path: /boot/vmlinuz\-linux
  output: /boot/vmlinuz\-linux
\- path: /efi/EFI/Linux/arch\-linux\&.efi
  output: /efi/EFI/Linux/arch\-linux\&.efi
keys:
  pk:
    privkey: /var/lib/sbctl/keys/PK/PK\&.key
    pubkey: /var/lib/sbctl/keys/PK/PK\&.pem
    type: file
  kek:
    privkey: /var/lib/sbctl/keys/KEK/KEK\&.key
    pubkey: /var/lib/sbctl/keys/KEK/KEK\&.pem
    type: file
  db:
    privkey: /var/lib/sbctl/keys/db/db\&.key
    pubkey: /var/lib/sbctl/keys/db/db\&.pem
    type: file
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBsbctl\fR(8)
.SH "AUTHORS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Morten Linderud <morten@linderud\&.pw>
.RE