19.3 Using appended signatures in GRUB

GRUB supports verifying Linux-style ’appended signatures’ for Linux on Power LPAR secure boot. Appended signatures are PKCS#7 messages containing a signature over the contents of a file, plus some metadata, appended to the end of a file. A file with an appended signature ends with the magic string:

~Module signature appended~\n

where \n represents the line feed character, 0x0a.

Linux on Power LPAR secure boot is controlled by ’ibm,secure-boot’ device tree property and if this property is set to 2 (‘enforce’), GRUB enters lockdown mode. There are three secure boot modes. They are

• ‘0 - disabled’: Secure boot is disabled. This is the default.
• ‘1 - audit’: Enforce signature verification by setting check_appended_signatures (see check_appended_signatures) to yes and do not enter lockdown mode. Signature verification is performed and if signature verification fails, display the errors and allow the boot to continue.
• ‘2 - enforce’: Enter lockdown mode and enforce signature verification by setting check_appended_signatures (see check_appended_signatures) to yes.

Note that Linux on Power LPAR only supports ‘0 - disabled’ and ‘2 - enforce’, and ‘1 - audit’ is considered as secure boot being disabled.

Enforcement of signature verification is controlled by the environment variable check_appended_signatures (see check_appended_signatures).

• ‘no’: No verification is performed. This is the default.
• ‘yes’: Signature verification is performed and if signature verification fails, display the errors and stop the boot. Signature verification cannot be disabled by setting the check_appended_signatures variable back to ‘no’.

To enable appended signature verification, load the appendedsig module and an X.509 certificate for verification. It is recommended to build the appendedsig module into the core GRUB image.

Key management is controlled by the environment variable appendedsig_key_mgmt (see appendedsig_key_mgmt).

• ‘static’: Enforce static key management signature verification. This is the default. When GRUB is in lockdown mode, then the user cannot change the value of the appendedsig_key_mgmt.
• ‘dynamic’: Enforce dynamic key management signature verification. When GRUB is in lockdown mode, then the user cannot change the value of the appendedsig_key_mgmt.

In static key management mode, certificates will be built into the core image using the --x509 parameter to grub-mkimage. The list of trusted certificates available at boot time can be shown using append_list_db (see append_list_db). Distrusted certificates can be explicitly removed from the db using append_add_dbx_cert (see append_add_dbx_cert). Also, trusted certificates can be explicitly added to the db using append_add_db_cert (see append_add_db_cert).

In dynamic key management mode, db and dbx are read from the Platform KeyStore (PKS). If db does not exist in PKS, static keys (built-in keys) are used as the default keys. The list of trusted certificates and binary hashes available at boot time can be shown using append_list_db (see append_list_db) and the list of distrusted certificates and binary/certificate hashes available at boot time can be shown using append_list_dbx (see append_list_dbx). The trusted certificates and binary hashes can be explicitly added to the db using append_add_db_cert (see append_add_db_cert) and append_add_db_hash (see append_add_db_hash). Distrusted certificates can be explicitly added to the dbx using append_add_dbx_cert (see append_add_dbx_cert) and distrusted certificate/binary hashes can be explicitly added to the dbx using append_add_dbx_hash (see append_add_dbx_hash).

A file can be explicitly verified using append_verify (see append_verify).

Note that when the environment variable check_appended_signatures is set to yes, the append_add_db_cert and append_add_dbx_cert commands only accept the file ‘X509_certificate’ that is signed with an appended signature (see Signing certificate and hash files), and the append_add_db_hash and append_add_dbx_hash commands only accept the file ‘hash_file’ that is signed with an appended signature (see Signing certificate and hash files). The signature is verified by the appendedsig module. When the environment variable check_appended_signatures is set to no, these commands accept files without an appended signature.

Also, note that ‘X509_certificate’ should be in DER-format and ‘hash_file’ should be in binary format. Only SHA-256, SHA-384, or SHA-512 hashes of binary/certificate are allowed. Certificates/hashes of certificates/binaries added through append_add_db_cert, append_add_dbx_cert, append_add_db_hash, and append_add_dbx_hash will not be persisted across boots.

Only signatures created using SHA-256 or SHA-512 hash algorithm along with RSA keys of size 2048, 3072, or 4096 bits are supported.

A file can be signed with the sign-file utility supplied with the Linux kernel source. For example, if you have signing.key as the private key and certificate.der as the X.509 certificate containing the public key:

sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed

Once signature verification is turned on, the following file types must carry appended signatures:

1. Linux kernels
2. GRUB modules, except those built in to the core image
3. Any new certificate or binary hash files to be trusted
4. Any new certificate/binary hash files to be distrusted

When GRUB is in lockdown mode (when secure boot mode is set to enforce), signature verification cannot be disabled by setting the check_appended_signatures (see check_appended_signatures) variable to no or using the load_env (see load_env) command from the GRUB console.