CCSecureBoot

CCSecureBoot

Implements boot security in CC: Tweaked.

Installation

CC: Tweaked 1.112.0 or later must already be installed.

Simply install a built JAR into your mods folder. This mod only operates on the server side, so multiplayer clients do not need it installed.

Usage

By default, secure boot is disabled for all computers. To enable secure boot for a computer, run the enroll-secure-boot program. This program will generate a new key for the computer, placing it on a floppy disk for safe keeping.

enroll-secure-boot will first display some important information about secure boot, and asks for confirmation to continue. Then it will prompt for a password for the key - this is optional, but recommended to prevent accidental key leakage. If a disk isn't detected, it will then wait for a disk to be inserted. Once ready, the key will be generated and saved, and a recovery boot config will be placed on the disk as well.

When secure boot is enabled, the computer will only be able to boot from files that have a signature alongside them. Files can be signed with the sign command, which will create a .sig file next to the program. The key disk must be in a disk drive to sign.

Secure boot disables direct access to the shell - it will only boot to startup.lua by default (which must be signed). If the key disk is inserted, a boot menu will appear with the option to start a shell.

Secure boot runs on pxboot, which allows customizing the boot screen, including adding more menu entries, changing the default entry and timeout, and stylizing the menu. Additional configs can be loaded from /pxboot_config.lua, which must be signed as well. See the repo for more information on how to write configs for pxboot.

Secure boot may be disabled for a computer by running unenroll-secure-boot on any computer with the key card inserted. The computer is unenrolled by key card, not by computer ID, so a computer which cannot be booted anymore can be unenrolled. The key will be revoked as well, which allows preventing abuse if a key is leaked.

If the key for a computer is lost, there is no way to recover the computer - it will no longer be possible to modify the boot files or unenroll the computer from secure boot. Keep the key disk in a safe place, away from other players.

Securing your code

Secure boot only ensures a root of trust going into your program - it does not guarantee that your computer as a whole is safe. It is up to you to make sure your code is secure from hacks, including checking all code that's loaded and avoiding unsafe programs.

When secure boot is enabled, due to the way the boot manager is set up, you are automatically protected from the two most basic bypasses for programs: holding Ctrl+T to terminate to the shell, and inserting a disk with a startup file. You won't have to protect against these in your program (though you should ideally handle terminate events safely instead of erroring and restarting).

To help with code signing, CCSecureBoot exposes an easy-to-use library based on the same code that the boot manager uses. Simply call dofile("/rom/modules/main/codesign.lua") to gain access to a few functions that make checking signatures easier:

• codesign.verify(path): Simply verifies the signature of a file, and returns a boolean whether the file is safe.
• codesign.execute(cmd, ...): A wrapper for shell.execute that checks the signature of the command. This doesn't allow ROM programs, however - use normal shell.execute to run known safe programs.
• codesign.loadfile(path, mode, env): A wrapper for loadfile that checks the signature of the file. This automatically allows modules in /rom/modules, but will not work for the rest of the ROM.
• codesign.dofile(path): A wrapper for dofile that checks the signature of the file. This automatically allows modules in /rom/modules, but will not work for the rest of the ROM.
• codesign.enforceModuleSigning(): Requires code signing on all modules loaded through require. Call this once at the start of your program - it will stay active for the rest of the program's lifetime. This does not survive inside codesign.execute/shell.execute calls - call it again inside a new program.
• codesign.sign(data, password): Generates a signature blob for the data provided. This is in the same format as .sig files. The key disk must be inserted, and if the key is password-protected, the password must be provided.
• codesign.load(data, sig, name, mode, env): A wrapper for load that checks the signature of the code, using a provided signature blob.

If your program uses modules via require, enable module signing before loading any modules, to make sure they are properly signed and not replaced with untrusted code:

-- require could load a local module instead of the one in ROM - always use dofile to load codesign:
local codesign = dofile "/rom/modules/main/codesign.lua"
codesign.enforceModuleSigning()
-- Now require is safe to load external modules:
local yourmod = require "yourmod"
-- ...

As a reminder, never load untrusted code through load without a restricted environment, especially when the input is from a modem. If you want to load code, give it a highly restricted environment with only the functions required, if any. (Despite the fact that textutils.unserialize loads code, it uses an empty environment, so it's considered safe.)

Inner workings

CCSecureBoot uses the PKCS or S/MIME protocol stack for storing cryptographic info, and uses Ed25519 for signatures. Most of the heavy lifting is done by libcert and ccryptolib on the Lua side, and Bouncy Castle on the Java side.