Probably the simplest way to get some debug information from your kernel code is by printing out various information with the kernel's equivalent of printf - the printk function and its derivatives. The k in printk is used to specifically remind kernel developers that the environment is different.
printk: This tool shows the kernel messages at boot and each code tells different behavior by the kernel.
Editing /etc/sysctl.conf with Administration Privilege (set to 3416)
These values influence printk() behavior when printing or logging error messages. See man 2 syslog for more info on the different loglevels.
Grsecurity is an extensive security module and patch for the Linux kernel to prevent cyber attacks with many options for both desktop and server.
Grsecurity Kernel Parameters:
Gresecurity Setup with Administration Privilege:
There are a few tricks to protect logging system for more safety
Editing /etc/ssh/sshd_config with Administration Privilege to:
AllowUsers (username)
Protocol 2
ClientAliveCountMax 2
ClientAliveInterval 300
IgnoreRhosts yes
MaxAuthTries 3
PasswordAuthentication no
PermitEmptyPasswords no
PermitRootLogin no
Port 2222
UseDNS yes
X11Forwarding no
Editing /etc/sysctl.conf with Administration Privilege to:
# Controls IP packet forwarding
net.ipv4.ip_forward = 0
# Do not accept source routing
net.ipv4.conf.default.accept_source_route = 0
# Controls the System Request debugging functionality of the kernel
kernel.sysrq = 0
# Controls whether core dumps will append the PID to the core filename
# Useful for debugging multi-threaded applications
kernel.core_uses_pid = 1
# Controls the use of TCP syncookies
# Turn on SYN-flood protections
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_synack_retries = 5
########### IPv4 networking start ###############
# Send redirects, if router, but this is just server
# So no routing allowed
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.default.send_redirects = 0
# Accept packets with SRR option? No
net.ipv4.conf.all.accept_source_route = 0
# Accept Redirects? No, this is not router
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.all.secure_redirects = 0
# Log packets with impossible addresses to kernel log? yes
net.ipv4.conf.all.log_martians = 1
net.ipv4.conf.default.accept_source_route = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv4.conf.default.secure_redirects = 0
# Ignore all ICMP ECHO and TIMESTAMP requests sent to it via broadcast/multicast
net.ipv4.icmp_echo_ignore_broadcasts = 1
# Prevent against the common 'syn flood attack'
net.ipv4.tcp_syncookies = 1
# Enable source validation by reversed path, as specified in RFC1812
net.ipv4.conf.all.rp_filter = 1
# Controls source route verification
net.ipv4.conf.default.rp_filter = 1
########### IPv6 networking start ###############
# Number of Router Solicitations to send until assuming no routers are present.
# This is host and not router
net.ipv6.conf.default.router_solicitations = 0
# Accept Router Preference in RA?
net.ipv6.conf.default.accept_ra_rtr_pref = 0
# Learn Prefix Information in Router Advertisement
net.ipv6.conf.default.accept_ra_pinfo = 0
# Setting controls whether the system will accept Hop Limit settings from a router advertisement
net.ipv6.conf.default.accept_ra_defrtr = 0
#router advertisements can cause the system to assign a global unicast address to an interface
net.ipv6.conf.default.autoconf = 0
#how many neighbor solicitations to send out per address?
net.ipv6.conf.default.dad_transmits = 0
# How many global unicast IPv6 addresses can be assigned to each interface?
net.ipv6.conf.default.max_addresses = 1
########## IPv6 networking ends ##############
#Enable ExecShield protection
#Set value to 1 or 2 (recommended)
#kernel.exec-shield = 2
#kernel.randomize_va_space=2
# TCP and memory optimization
# increase TCP max buffer size setable using setsockopt()
#net.ipv4.tcp_rmem = 4096 87380 8388608
#net.ipv4.tcp_wmem = 4096 87380 8388608
# increase Linux auto tuning TCP buffer limits
#net.core.rmem_max = 8388608
#net.core.wmem_max = 8388608
#net.core.netdev_max_backlog = 5000
#net.ipv4.tcp_window_scaling = 1
# increase system file descriptor limit
fs.file-max = 65535
#Allow for more PIDs
kernel.pid_max = 65536
#Increase system IP port limits
net.ipv4.ip_local_port_range = 2000 65000
# RFC 1337 fix
net.ipv4.tcp_rfc1337=1
The sysctl is a utility which is used to manage networking and other low-level protective Linux kernel parameters at runtime.
This cheatsheet allows quickly secure currently running server thought this powerful tool.
The configuration file for sysctl is located at /etc/sysctl.conf and contains the values to be read and set on system boot. The below parameters assure security for most Linux servers:
net.ipv4.tcp_syncookies = 1
net.ipv4.icmp_echo_ignore_broadcasts = 1
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.all.accept_source_route = 0
net.ipv4.conf.all.rp_filter = 1
net.ipv4.conf.all.log_martians = 1
net.ipv4.conf.all.send_redirects = 0
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_keepalive_time = 1800
Below is a description of sysctl directives used to secure server:
tcp_syncookies
This parameter can help to prevent SYN flood DDoS attacks by testing the validity of the SYN packets. For security reasons it is recommended to enable the parameter. Note that the process is conducted without consuming memory or connection resources.
ignore_broadcasts
A ping broadcast is used to see what hosts in LAN are up, but there are other ways to do this. It is safer to disable this option because ICMP (ping) broadcasts and multicasts are usually a sign of Smurf attack.
accept_redirects
The parameter allows to enable or disable ICMP redirects acceptance. ICMP redirects are important to routers, but can create security problems for servers, so it is recommended to set the parameter to off.
accept_source_route
Tells netfilter to accept or decline source routed packets. Source routed packets are security risk, because they can can allow routing packets through an untrusted or insecure interface.
rp_filter
This parameter controls reverse path filtering, which tries to ensure packets use legitimate source addresses. When is turned on it can prevent some IP spoofing attacks.
log_martians
The parameter allows to keep track of packets which could potentially indicate an attack on server. This packets are those that includes impossible IP addresses, bad source routing, bad redirect packets and others.
send_redirects
Enables or disables ICMP redirects which are used mainly by routers to send out ICMP redirects to other hosts. For security reasons, it is recommended to disable this option.
fin_timeout
Tells Netfilter how much seconds keep sockets in FIN-WAIT-2 state which means that connection is closed, and the socket is waiting for a shutdown from the remote end. Decreasing the value to 30 can avoid some DDoS attacks or other problems that arose from getting huge amounts of connections
tcp_keepalive_time
Tells the Netfilter how often to send TCP keepalive packets to keep an connection alive if it is currently unused. The value 1800, or 30 minutes, is a good value for most servers.
System Hardening "Choose system security hardening options:"
System Configuration "Choose the services you would like to be started at boot:"
Cryptsetup provides an interface for configuring encryption on block devices (such as /home or swap partitions), using the Linux kernel device mapper target dm-crypt. It features integrated Linux Unified Key Setup (LUKS) support.
Cryptmount: utility for creating encrypted filesystems & swap partitions and which allows an ordinary user to mount/unmount filesystems without requiring superuser privileges.
Name
cryptsetup - setup cryptographic volumes for dm-crypt (including LUKS extension)
Synopsis
cryptsetup
Description
cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings. For basic (plain) dm-crypt mappings, there are four operations.
Actions
These strings are valid for
create
creates a mapping with
remove
removes an existing mapping
status
reports the status for the mapping
resize
resizes an active mapping
If --size (in sectors) is not specified, the size of the underlying block device is used.
Luks Extension
LUKS, Linux Unified Key Setup, is a standard for hard disk encryption. It standardizes a partition header, as well as the format of the bulk data. LUKS can manage multiple passwords, that can be revoked effectively and that are protected against dictionary attacks with PBKDF2.
These are valid LUKS actions:
luksFormat
initializes a LUKS partition and sets the initial key, either via prompting or via
luksOpen
opens the LUKS partition
luksClose
identical to remove.
luksSuspend
suspends active device (all IO operations are frozen) and wipes encryption key from kernel. Kernel version 2.6.19 or later is required.
After that operation you have to use luksResume to reinstate encryption key (and resume device) or luksClose to remove mapped device.
WARNING: never try to suspend device where is the cryptsetup binary itself.
luksResume
Resumes suspended device and reinstates encryption key. You will need provide passphrase identical to luksOpen command (using prompting or key file).
luksAddKey
add a new key file/passphrase. An existing passphrase or key file (via --key-file) must be supplied. The key file with the new material is supplied as a positional argument.
luksRemoveKey
remove supplied key or key file from LUKS device
luksKillSlot
wipe key with number
key file (via --key-file) must be supplied.
luksUUID
print UUID, if
set new UUID if --uuid option is specified.
isLuks
returns true, if
luksDump
dumps the header information of a LUKS partition.
If --dump-master-key option is used, the volume (master) key is dumped instead of keyslot info. Because this information can be used to access encrypted device without passphrase knowledge (even without LUKS header) use this option very carefully.
Dump with volume key (either printed or stored to file) should be always stored encrypted and on safe place.
LUKS passphrase or key file is required for volume key dump.
luksHeaderBackup
Stores binary backup of LUKS header and keyslot areas.
WARNING: Please note that with this backup file (and old passphrase knowledge) you can decrypt data even if old passphrase was wiped from real device.
Also note that anti-forensic splitter is not used during manipulation with backup file.
luksHeaderRestore
Restores binary backup of LUKS header and keyslot areas from specified file.
WARNING: All the keyslot areas are overwritten, only active keyslots form backup file are available after issuing this command.
This command allows restoring header if device do not contain LUKS header or if the master key size and data offset in LUKS header on device match the backup file.
For more information about LUKS, see http://code.google.com/p/cryptsetup/wiki/Specification
Options
--verbose, -v Print more verbose messages.
--debug Run in debug mode with full diagnostic logs.
--hash, -h For create action specifies hash to use for password hashing.
For luksFormat action specifies hash used in LUKS key setup scheme and volume key digest.
WARNING: setting hash other than sha1 causes LUKS device incompatible with older version of cryptsetup.
The hash string is passed to libgcrypt, so all hash algorithms are supported (for luksFormat algorithm must provide at least 20 byte long hash). Default is set during compilation, compatible values with old version of cryptsetup are "ripemd160" for create action and "sha1" for luksFormat.
Use cryptsetup --help to show defaults.
--cipher, -c set cipher specification string.
Default mode is configurable during compilation, you can see compiled-in default using cryptsetup --help. If not changed, the default is for plain dm-crypt and LUKS mappings "aes-cbc-essiv:sha256".
For pre-2.6.10 kernels, use "aes-plain" as they don't understand the new cipher spec strings. To use ESSIV, use "aes-cbc-essiv:sha256".
For XTS mode, kernel version 2.6.24 or more recent is required. Use "aes-xts-plain" cipher specification and set key size to 256 (or 512) bits (see -s option).
--verify-passphrase, -y query for passwords twice. Useful when creating a (regular) mapping for the first time, or when running luksFormat.
--key-file, -d use file as key material.
With LUKS, key material supplied in key files via -d are always used for existing passphrases, except in luksFormat action where -d is equivalent to positional key file argument. If you want to set a new key via a key file, you have to use a positional arg to luksAddKey.
If the key file is "-", stdin will be used. With the "-" key file reading will not stop when new line character is detected. See section NOTES ON PASSWORD PROCESSING for more information.
--keyfile-size, -d value Limits read from keyfile to value bytes. Usable together with all comands using key file.
--new-keyfile-size value Limits read from new keyfile to value bytes in luksAddKey when adding new key file. Default is exhaustive read from key file.
--master-key-file Use pre-generated master key stored in file. For luksFormat it allows LUKS header reformatting with the same master key (if all other parameters are the same existing encrypted data remains intact).
For luksAddKey it allows adding new passphrase with only master key knowledge.
--dump-master-key For luksDump it allows LUKS header dump including volume (master) key. Use with care (this information allows access to device without passphrase knowledge).
See luksDump for more info.
--use-random, --use-urandom For luksFormat it defines which kernel random number generator will be used for long-term key (volume key).
See NOTES ON RNG for more information. Use cryptsetup --help to show default RNG.
--key-slot, -S For LUKS operations that add key material, this options allows to you specify which key slot is selected for the new key. This option can be used for luksFormat and luksAddKey.
--key-size, -s set key size in bits.
Has to be a multiple of 8 bits. The key size is limited by the used cipher. See output of /proc/crypto for more information. Can be used for create or luksFormat, all other LUKS actions will use key-size specified by the LUKS header. Default is set during compilation, if not changed it is 256 bits.
Use cryptsetup --help to show defaults.
--size, -b force the size of the underlying device in sectors. This option is only relevant for create and resize action.
--offset, -o start offset in the backend device (in 512-byte sectors). This option is only relevant for create action.
--skip, -p how many sectors of the encrypted data to skip at the beginning. This is different from the --offset options with respect to IV calculations. Using --offset will shift the IV calculation by the same negative amount. Hence, if --offset n, sector n will be the first sector on the mapping with IV 0. Using --skip would have resulted in sector n being the first sector also, but with IV n. This option is only relevant for create action.
--readonly set up a read-only mapping.
--iter-time, -i The number of milliseconds to spend with PBKDF2 password processing. This option is only relevant to the LUKS operations as luksFormat or luksAddKey.
--batch-mode, -q Do not ask for confirmation. Use with care! This option is only relevant for luksFormat, luksAddKey, luksRemoveKey or luksKillSlot.
--timeout, -t The number of seconds to wait before timeout. This option is relevant every time a password is asked, like create, luksOpen, luksFormat or luksAddKey. It has no effect if used in conjunction with –key-file.
--tries, -T How often the input of the passphrase shall be retried. This option is relevant every time a password is asked, like create, luksOpen, luksFormat or luksAddKey. The default is 3 tries.
--align-payload=value Align payload at a boundary of value 512-byte sectors. This option is relevant for luksFormat. If not specified, cryptsetup tries to use topology info provided by kernel for underlying device to get optimal alignment. If not available (or calculated value is multiple of default) data is by default aligned to 1 MiB boundary (2048 512-byte sectors).
--uuid=UUID Use provided UUID in luksFormat command instead of generating new one or change existing UUID in luksUUID command.
The UUID must be provided in standard UUID format (e.g. 12345678-1234-1234-1234-123456789abc).
--version Show the version.
Notes on Password Processing
From a terminal: Password processing is new-line sensitive, meaning the reading will stop after encountering n. It will process the read material (without newline) with the default hash or the hash given by --hash. After hashing, it will be cropped to the key size given by -s.
From stdin: Reading will continue until EOF (so using e.g. /dev/random as stdin will not work), with the trailing newline stripped. After that the read data will be hashed with the default hash or the hash given by --hash and the result will be cropped to the keysize given by -s. If "plain" is used as an argument to the hash option, the input data will not be hashed. Instead, it will be zero padded (if shorter than the keysize) or truncated (if longer than the keysize) and used directly as the key. No warning will be given if the amount of data read from stdin is less than the keysize.
From a key file: It will be cropped to the size given by -s. If there is insufficient key material in the key file, cryptsetup will quit with an error.
If --key-file=- is used for reading the key from stdin, no trailing newline is stripped from the input. Without that option, cryptsetup strips trailing newlines from stdin input.
Notes on Password Processing for Luks
LUKS uses PBKDF2 to protect against dictionary attacks (see RFC 2898).
LUKS will always do an exhaustive password reading. Hence, password can not be read from /dev/random, /dev/zero or any other stream that does not terminate.
For any password creation action (luksAddKey, or luksFormat), the user may specify how much the time the password processing should consume. Increasing the time will lead to a more secure password, but also will take luksOpen longer to complete. The default setting of one second is sufficient for good security.
Incoherent Behavior for Invalid Passwords/Keys
LUKS checks for a valid password or key when an encrypted partition is unlocked. Thus the luksOpen action fails with invalid password or key, contrary to the plain dm-crypt create action.
Please also be sure that you are using the same keyboard and language setting as during device format.
Notes on Supported Ciphers, Modes, Hashes and Key Sizes
The available combinations of ciphers, modes, hashes and key sizes depend on kernel support. See /proc/crypto for a list of available options. You might need to load additional kernel crypto modules in order to get more options.
For --hash option all algorithms supported by gcrypt library are available.
Notes on Passwords
Mathematics can't be bribed. Make sure you keep your passwords safe. There are a few nice tricks for constructing a fallback, when suddenly out of (or after being) blue, your brain refuses to cooperate. These fallbacks are possible with LUKS, as it's only possible with LUKS to have multiple passwords.
Notes on Rng
Random Number Generator (RNG) used in cryptsetup always uses kernel RNG without any modifications or additions to data stream procudes by kernel (like internal random pool operations or mixing with the other random sources).
There are two types of randomness cryptsetup/LUKS needs. One type (which always uses /dev/urandom) is used for salt, AF splitter and for wiping removed keyslot.
Second type is used for volume (master) key. You can switch between using /dev/random and /dev/urandom here, see --use-random and --use-urandom options. Using /dev/random on system without enough entropy sources can cause luksFormat to block until the requested amount of random data is gathered. See urandom(4) for more information.
GELI is a block device-layer disk encryption system written for FreeBSD, introduced in version 6.0. It uses the GEOM disk framework. It was designed and implemented by Paweł Jakub Dawidek.
NAME
geom -- universal control utility for GEOM classes
SYNOPSIS
geom class help
geom class list [-a] [name ...]
geom class status [-ags] [name ...]
geom class load [-v]
geom class unload [-v]
geom -p provider-name
geom -t
DESCRIPTION
The geom utility is used to control various GEOM classes. A class has to be aware of geom communication methods, but there are also some standard commands which can be used for existing geom unaware classes. Here is the list of standard commands:
help
List all available commands for the given class.
list
Print detailed information (within the given class) about all geoms (if no additional arguments were specified) or the given geoms. This command is only available if the given class exists in the kernel. Additional options include:
-a
Print information for geoms without providers.
status
Print general information (within the given class) about all geoms (if no additional arguments were specified) or the given geoms. This command is only available if the given class exists in the kernel.
Additional options include:
-a
When used with -g, print status for geoms without providers.
-g
Report statuses for geoms instead of providers.
-s
Produce script-friendly output.
load
Load the kernel module that implements the given class. This command is only available if the class does not yet exist in the kernel and the file geom_
unload
Unload the kernel module which implements the given class. This command is only available if the given class is loaded as a kernel module.
Additional options include:
-p provider-name
Print detailed information about the geom which provides provider-name.
-t
Display geoms hierarchy as a tree.
Class-specific commands are implemented as shared libraries which are stored in /lib/geom/ directory and are loaded via dlopen function when the class name is known. When a class-specific shared library exists, a direct utility should also be available under the name of gclass.
Currently available classes which are aware of geom:
+o CACHE
+o CONCAT
+o ELI
+o JOURNAL
+o LABEL
+o MIRROR
+o MOUNTVER
+o MULTIPATH
+o NOP
+o PART
+o RAID
+o RAID3
+o SCHED
+o SHSEC
+o STRIPE
+o VIRSTOR
ENVIRONMENT
The following environment variables affect the execution of geom:
GEOM_LIBRARY_PATH
Specifies the path where shared libraries are stored instead of /lib/geom/. Multiple paths can be specified with a colon-separated list of paths.
EXIT STATUS
Exit status is 0 on success, and 1 if the command fails.
EXAMPLES
The following example shows how to set up a stripe on three disks for automatic configuration:
geom stripe label -v -s 65536 data /dev/da0 /dev/da1 /dev/da2
or:
gstripe label -v -s 65536 data /dev/da0 /dev/da1 /dev/da2
Print the list of all providers from the DISK class:
geom disk list
Unload a kernel module which implements the MD class:
geom md unload
NAME
geli -- control utility for the cryptographic GEOM class
SYNOPSIS
To compile GEOM_ELI into your kernel, add the following lines to your kernel configuration file:
device crypto
options GEOM_ELI
Alternatively, to load the GEOM_ELI module at boot time, add the follow-
ing line to your loader.conf(5):
geom_eli_load="YES"
Usage of the
geli utility:
geli init [-bdgPTv] [-a aalgo] [-B backupfile] [-e ealgo] [-i iterations] [-J newpassfile] [-K newkeyfile] [-l keylen] [-s sectorsize] [-V version] prov ...
geli label - an alias for init
geli attach [-Cdprv] [-n keyno] [-j passfile] [-k keyfile] prov ...
geli detach [-fl] prov ...
geli stop - an alias for detach
geli onetime [-dT] [-a aalgo] [-e ealgo] [-l keylen] [-s sectorsize] prov
geli configure [-bBdDgGtT] prov ...
geli setkey [-pPv] [-i iterations] [-j passfile] [-J newpassfile] [-k keyfile] [-K newkeyfile] [-n keyno] prov
geli delkey [-afv] [-n keyno] prov
geli kill [-av] [prov ...]
geli backup [-v] prov file
geli restore [-fv] file prov
geli suspend [-v] -a | prov ...
geli resume [-pv] [-j passfile] [-k keyfile] prov
geli resize [-v] -s oldsize prov
geli version [prov ...]
geli clear [-v] prov ...
geli dump [-v] prov ...
geli list
geli status
geli load
geli unload
DESCRIPTION
The geli utility is used to configure encryption on GEOM providers.
The following is a list of the most important features:
+o Utilizes the crypto framework, so when there is crypto hardware available, geli will make use of it automatically.
+o Supports many cryptographic algorithms (currently AES-XTS, AES-CBC, Blowfish-CBC, Camellia-CBC and 3DES-CBC).
+o Can optionally perform data authentication (integrity verification) utilizing one of the following algorithms: HMAC/MD5, HMAC/SHA1, HMAC/RIPEMD160, HMAC/SHA256, HMAC/SHA384 or HMAC/SHA512.
+o Can create a User Key from up to two, piecewise components: a passphrase entered via prompt or read from one or more passfiles; a keyfile read from one or more files.
+o Allows encryption of the root partition. The user is asked for the passphrase before the root filesystem is mounted.
+o Strengthens the passphrase component of the User Key with: B. Kaliski, PKCS #5: Password-Based Cryptography Specification, Version 2.0., RFC, 2898.
+o Allows the use of two independent User Keys (e.g., a "user key" and a "company key").
+o It is fast - geli performs simple sector-to-sector encryption.
+o Allows the encrypted Master Key to be backed up and restored, so that if a user has to quickly destroy key material, it is possible to get the data back by restoring keys from backup.
+o Providers can be configured to automatically detach on last close, so users do not have to remember to detach providers after unmounting the filesystems.
+o Allows attaching a provider with a random, one-time Master Key, which is useful for swap partitions and temporary filesystems.
+o Allows verification of data integrity (data authentication).
+o Allows suspending and resuming encrypted devices.
The first argument to geli indicates an action to be performed:
init
Initialize providers which need to be encrypted. If multiple providers are listed as arguments, they will all be initialized with the same passphrase and/or User Key. A unique salt will be randomly generated for each provider to ensure the Master Key for each is unique. Here you can set up the cryptographic algorithm to use, Data Key length, etc. The last sector of the providers is used to store metadata. The init subcommand also automatically writes metadata backups to /var/backups/_prov_.eli file. The metadata can be recovered with the restore subcommand described below.
Additional options include:
-a aalgo
Enable data integrity verification (authentication) using the given algorithm. This will reduce the size of storage available and also reduce speed. For example, when using 4096 bytes sector and HMAC/SHA256 algorithm, 89% of the original provider storage will be available for use. Currently supported algorithms are: HMAC/MD5, HMAC/SHA1, HMAC/RIPEMD160, HMAC/SHA256, HMAC/SHA384 and HMAC/SHA512. If the option is not given, there will be no authentication, only encryption. The recommended algorithm is HMAC/SHA256.
-b
Try to decrypt this partition during boot, before the root partition is mounted. This makes it possible to use an encrypted root partition. One will still need bootable unencrypted storage with a /boot/ directory, which can be a CD-ROM disc or USB pen-drive, that can be removed after boot.
-B backupfile
File name to use for metadata backup instead of the default /var/backups/_prov_.eli. To inhibit backups, you can use none as the backupfile. If multiple providers were initialized in the one command, you can use PROV (all upper-case) in the file name, and it will be replaced with the provider name. If PROV is not found in the file name and multiple providers were initialized in the one command, -_prov_ will be appended to the end of the file name specified.
-d
When entering the passphrase to boot from this encrypted root filesystem, echo `*' characters. This makes the length of the passphrase visible.
-e ealgo
Encryption algorithm to use. Currently supported algorithms are: AES-XTS, AES-CBC, Blowfish-CBC, Camellia-CBC, 3DES-CBC, and NULL. The default and recommended algorithm is AES-XTS. NULL is unencrypted.
-g
Enable booting from this encrypted root filesystem. The boot loader prompts for the passphrase and loads loader(8) from the encrypted partition.
-i iterations
Number of iterations to use with PKCS#5v2 when processing User Key passphrase component. If this option is not specified, geli will find the number of iterations which is equal to 2 seconds of crypto work. If 0 is given, PKCS#5v2 will not be used. PKCS#5v2 processing is performed once, after all parts of the passphrase component have been read.
-J newpassfile
Specifies a file which contains the passphrase component of the User Key (or part of it). If newpassfile is given as -, standard input will be used. Only the first line (excluding newline character) is taken from the given file. This argument can be specified multiple times, which has the effect of reassembling a single passphrase split across multiple files. Cannot be combined with the -P option.
-K newkeyfile
Specifies a file which contains the keyfile component of the User Key (or part of it). If newkeyfile is given as -, standard input will be used. This argument can be specified multiple times, which has the effect of reassembling a single keyfile split across multiple keyfile parts.
-l keylen
Data Key length to use with the given cryptographic algorithm. If the length is not specified, the selected algorithm uses its default key length.
AES-XTS 128, 256
AES-CBC, Camellia-CBC 128, 192, 256
Blowfish-CBC 128 + n * 32, for n=[0..10]
3DES-CBC 192
-P
Do not use a passphrase as a component of the User Key. Cannot be combined with the -J option.
-s sectorsize
Change decrypted provider's sector size. Increasing the sector size allows increased performance, because encryption/decryption which requires an initialization vector is done per sector; fewer sectors means less computational work.
-T
Don't pass through BIO_DELETE calls (i.e., TRIM/UNMAP). This can prevent an attacker from knowing how much space you're actually using and which sectors contain live data, but will also prevent the backing store (SSD, etc) from reclaiming space you're not using, which may degrade its performance and lifespan. The underlying provider may or may not actually obliterate the deleted sectors when TRIM is enabled, so it should not be considered to add any security.
-V version
Metadata version to use. This option is helpful when creating a provider that may be used by older FreeBSD/GELI versions. Consult the HISTORY section to find which metadata version is supported by which FreeBSD version. Note that using an older version of metadata may limit the number of features available.
attach
Attach the given providers. The encrypted Master Keys are loaded from the metadata and decrypted using the given passphrase/keyfile and new GEOM providers are created using the specified provider names. A ".eli" suffix is added to the user specified provider names. Multiple providers can only be attached with a single attach command if they all have the same passphrase and keyfiles.
Additional options include:
-C
Do a dry-run decryption. This is useful to verify passphrase and keyfile without decrypting the device.
-d
If specified, the decrypted providers are detached automatically on last close, so the user does not have to remember to detach providers after unmounting the filesystems. This only works when providers were opened for writing, and will not work if the filesystems on the providers were mounted read-only. Probably a better choice is the -l option for the detach subcommand.
-n keyno
Specifies the index number of the Master Key copy to use (could be 0 or 1). If the index number is not provided all keys will be tested.
-j passfile
Specifies a file which contains the passphrase component of the User Key (or part of it). For more information see the description of the -J option for the init subcommand. The same passfiles are used for all listed providers.
-k keyfile
Specifies a file which contains the keyfile component of the User Key (or part of it). For more information see the description of the -K option for the init subcommand. The same keyfiles are used for all listed providers.
-p
Do not use a passphrase as a component of the User Keys. Cannot be combined with the -j option.
-r
Attach read-only providers. They are not opened for writing.
detach
Detach the given providers, which means remove the devfs entry and clear the Master Key and Data Keys from memory.
Additional options include:
-f
Force detach - detach even if the provider is open.
-l
Mark provider to detach on last close, after the last filesystem has been unmounted. If this option is specified, the provider will not be detached while it is open, but will be automatically detached when it is closed for the last time even if it was only opened for reading.
onetime
Attach the given providers with a random, one-time (ephemeral) Master Key. The command can be used to encrypt swap partitions or temporary filesystems.
Additional options include:
-a aalgo
Enable data integrity verification (authentication). For more information, see the description of the init subcommand.
-e ealgo
Encryption algorithm to use. For more information, see the description of the init subcommand.
-d
Detach on last close, after the last filesystem has been unmounted. Note: this option is not usable for temporary filesystems as the provider is detached after the filesystem has been created. It still can, and should, be used for swap partitions. For more information, see the description of the attach subcommand.
-l keylen
Data Key length to use with the given cryptographic algorithm. For more information, see the description of the init subcommand.
-s sectorsize
Change decrypted provider's sector size. For more information, see the description of the init subcommand.
-T
Disable TRIM/UNMAP passthru. For more information, see the description of the init subcommand.
configure
Change configuration of the given providers.
Additional options include:
-b
Set the BOOT flag on the given providers. For more information, see the description of the init subcommand.
-B
Remove the BOOT flag from the given providers.
-d
When entering the passphrase to boot from this encrypted root filesystem, echo `*' characters. This makes the length of the passphrase visible.
-D
Disable echoing of any characters when a passphrase is entered to boot from this encrypted root filesystem. This hides the passphrase length.
-g
Enable booting from this encrypted root filesystem. The boot loader prompts for the passphrase and loads loader from the encrypted partition.
-G
Deactivate booting from this encrypted root partition.
-t
Enable TRIM/UNMAP passthru. For more information, see the description of the init subcommand.
-T
Disable TRIM/UNMAP passthru.
setkey
Install a copy of the Master Key into the selected slot, encrypted with a new User Key. If the selected slot is populated, replace the existing copy. A provider has one Master Key, which can be stored in one or both slots, each encrypted with an independent User Key. With the init subcommand, only key number 0 is initialized. The User Key can be changed at any time: for an attached provider, for a detached provider, or on the backup file. When a provider is attached, the user does not have to provide an existing passphrase/keyfile.
Additional options include:
-i iterations
Number of iterations to use with PKCS#5v2. If 0 is given, PKCS#5v2 will not be used. To be able to use this option with the setkey subcommand, only one key has to be defined and this key must be changed.
-j passfile
Specifies a file which contains the passphrase component of a current User Key (or part of it).
-J newpassfile
Specifies a file which contains the passphrase component of the new User Key (or part of it).
-k keyfile
Specifies a file which contains the keyfile component of a current User Key (or part of it).
-K newkeyfile
Specifies a file which contains the keyfile component of the new User Key (or part of it).
-n keyno
Specifies the index number of the Master Key copy to change (could be 0 or 1). If the provider is attached and no key number is given, the key used for attaching the provider will be changed. If the provider is detached (or we are operating on a backup file) and no key number is given, the first Master Key copy to be successfully decrypted with the provided User Key passphrase/keyfile will be changed.
-p
Do not use a passphrase as a component of the current User Key. Cannot be combined with the -j option.
-P
Do not use a passphrase as a component of the new User Key. Cannot be combined with the -J option.
delkey
Destroy (overwrite with random data) the selected Master Key copy. If one is destroying keys for an attached provider, the provider will not be detached even if all copies of the Master Key are destroyed. It can even be rescued with the setkey subcommand because the Master Key is still in memory.
Additional options include:
-a
Destroy all copies of the Master Key (does not need -f option).
-f
Force key destruction. This option is needed to destroy the last copy of the Master Key.
-n keyno
Specifies the index number of the Master Key copy. If the provider is attached and no key number is given, the key used for attaching the provider will be destroyed. If provider is detached (or we are operating on a backup file) the key number has to be given.
kill
This command should be used only in emergency situations. It will destroy all copies of the Master Key on a given provider and will detach it forcibly (if it is attached). This is absolutely a one-way command - if you do not have a metadata backup, your data is gone for good. In case the provider was attached with the -r flag, the keys will not be destroyed, only the provider will be detached.
Additional options include:
-a
If specified, all currently attached providers will be killed.
backup
Backup metadata from the given provider to the given file.
restore
Restore metadata from the given file to the given provider.
Additional options include:
-f
Metadata contains the size of the provider to ensure that the correct partition or slice is attached. If an attempt is made to restore metadata to a provider that has a different size, geli will refuse to restore the data unless the -f switch is used. If the partition or slice has been grown, the resize subcommand should be used rather than attempting to relocate the metadata through backup and restore.
suspend
Suspend device by waiting for all inflight requests to finish, clearing all sensitive information such as the Master Key and Data Keys from kernel memory, and blocking all further I/O requests until the resume subcommand is executed. This functionality is useful for laptops. Suspending a laptop should not leave an encrypted device attached. The suspend subcommand can be used rather than closing all files and directories from filesystems on the encrypted device, unmounting the filesystem, and detaching the device. Any access to the encrypted device will be blocked until the Master Key is reloaded through the resume subcommand. Thus there is no need to close nor unmount anything. The suspend subcommand does not work with devices created with the onetime subcommand. Please note that sensitive data might still be present in memory locations such as the filesystem cache after suspending an encrypted device.
Additional options include:
-a
Suspend all geli devices.
resume
Resume previously suspended device. The caller must ensure that executing this subcommand does not access the suspended device, leading to a deadlock. For example, suspending a device which contains the filesystem where the geli utility is stored is a bad idea.
Additional options include:
-j passfile
Specifies a file which contains the passphrase component of the User Key, or part of it. For more information see the description of the -J option for the init subcommand.
-k keyfile
Specifies a file which contains the keyfile component of the User Key, or part of it. For more information see the description of the -K option for the init subcommand.
-p
Do not use a passphrase as a component of the User Key. Cannot be combined with the -j option.
resize
Inform geli that the provider has been resized. The old metadata block is relocated to the correct position at the end of the provider and the provider size is updated.
Additional options include:
-s oldsize
The size of the provider before it was resized.
version
If no arguments are given, the version subcommand will print the version of geli userland utility as well as the version of the ELI GEOM class.
If GEOM providers are specified, the version subcommand will print metadata version used by each of them.
clear
Clear metadata from the given providers. WARNING: This will erase with zeros the encrypted Master Key copies stored in the metadata.
dump
Dump metadata stored on the given providers.
list See geom.
status See geom.
load See geom.
unload See geom.
Additional options include:
-v
Be more verbose.
KEY SUMMARY
Master Key
Upon init, the geli utility generates a random Master Key for the provider. The Master Key never changes during the lifetime of the provider. Each copy of the provider metadata, active or backed up to a file, can store up to two, independently-encrypted copies of the Master Key.
User Key
Each stored copy of the Master Key is encrypted with a User Key, which is generated by the geli utility from a passphrase and/or a keyfile. The geli utility first reads all parts of the keyfile in the order specified on the command line, then reads all parts of the stored passphrase in the order specified on the command line. If no passphrase parts are specified, the system prompts the user to enter the passphrase. The passphrase is optionally strengthened by PKCS#5v2. The User Key is a digest computed over the concatenated keyfile and passphrase.
Data Key
During operation, one or more Data Keys are deterministically derived by the kernel from the Master Key and cached in memory. The number of Data Keys used by a given provider, and the way they are derived, depend on the GELI version and whether the provider is configured to use data authentication.
SYSCTL VARIABLES
The following sysctl variables can be used to control the behavior of the ELI GEOM class. The default value is shown next to each variable. Some variables can also be set in /boot/loader.conf.
kern.geom.eli.version
Version number of the ELI GEOM class.
kern.geom.eli.debug: 0
Debug level of the ELI GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0, minimal debug information is printed. If set to 3, the maximum amount of debug information is printed.
kern.geom.eli.tries: 3
Number of times a user is asked for the passphrase. This is only used for providers which are attached on boot, before the root filesystem is mounted. If set to 0, attaching providers on boot will be disabled. This variable should be set in /boot/loader.conf.
kern.geom.eli.overwrites: 5
Specifies how many times the Master Key is overwritten with random values when it is destroyed. After this operation it is filled with zeros.
kern.geom.eli.visible_passphrase: 0
If set to 1, the passphrase entered on boot will be visible. This alternative should be used with caution as the entered passphrase can be logged and exposed via dmesg. This variable should be set in /boot/loader.conf.
kern.geom.eli.threads: 0
Specifies how many kernel threads should be used for doing software cryptography. Its purpose is to increase performance on SMP systems. If set to 0, a CPU-pinned thread will be started for every active CPU.
kern.geom.eli.batch: 0
When set to 1, can speed-up crypto operations by using batching. Batching reduces the number of interrupts by responding to a group of crypto requests with one interrupt. The crypto card and the driver has to support this feature.
kern.geom.eli.key_cache_limit: 8192
Specifies how many Data Keys to cache. The default limit (8192 keys) will allow caching of all keys for a 4TB provider with 512 byte sectors and will take around 1MB of memory.
kern.geom.eli.key_cache_hits
Reports how many times we were looking up a Data Key and it was already in cache. This sysctl is not updated for providers that need fewer Data Keys than the limit specified in kern.geom.eli.key_cache_limit.
kern.geom.eli.key_cache_misses
Reports how many times we were looking up a Data Key and it was not in cache. This sysctl is not updated for providers that need fewer Data Keys than the limit specified in kern.geom.eli.key_cache_limit.
EXIT STATUS
Exit status is 0 on success, and 1 if the command fails.
DEPRECATION NOTICE
Support for the Blowfish-CBC and 3DES-CBC cryptographic algorithms and HMAC/MD5 authentication algorithm will be removed in FreeBSD 13.0. New volumes cannot be created using these algorithms. Existing volumes should be migrated to a new volume that uses non-deprecated algorithms.
EXAMPLES
Initialize a provider which is going to be encrypted with a passphrase and random data from a file on the user's pen drive. Use 4kB sector size. Attach the provider, create a filesystem, and mount it. Do the work. Unmount the provider and detach it:
# dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
# geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
Enter new passphrase:
Reenter new passphrase:
# geli attach -k /mnt/pendrive/da2.key /dev/da2
Enter passphrase:
# dd if=/dev/random of=/dev/da2.eli bs=1m
# newfs /dev/da2.eli
# mount /dev/da2.eli /mnt/secret
...
# umount /mnt/secret
# geli detach da2.eli
Create an encrypted provider, but use two User Keys: one for your employee and one for you as the company's security officer (so it is not a tragedy if the employee "accidentally" forgets his passphrase):
# geli init /dev/da2
Enter new passphrase: (enter security officer's passphrase)
Reenter new passphrase:
# geli setkey -n 1 /dev/da2
Enter passphrase: (enter security officer's passphrase)
Enter new passphrase: (let your employee enter his passphrase ...)
Reenter new passphrase: (... twice)
You are the security officer in your company. Create an encrypted provider for use by the user, but remember that users forget their passphrases, so backup the Master Key with your own random key:
# dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
# geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e
# geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname`
(use key number 0, so the encrypted Master Key will be re-encrypted by this)
# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e
(allow the user to enter his passphrase)
Enter new passphrase:
Reenter new passphrase:
Encrypted swap partition setup:
# dd if=/dev/random of=/dev/ada0s1b bs=1m
# geli onetime -d -e 3des ada0s1b
# swapon /dev/ada0s1b.eli
The example below shows how to configure two providers which will be attached on boot, before the root filesystem is mounted. One of them is using passphrase and three keyfile parts and the other is using only a keyfile in one part:
# dd if=/dev/random of=/dev/da0 bs=1m
# dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
# dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
# dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
# geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
Enter new passphrase:
Reenter new passphrase:
# dd if=/dev/random of=/dev/da1s3a bs=1m
# dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
# geli init -b -P -K /boot/keys/da1s3a.key da1s3a
The providers are initialized, now we have to add these lines to /boot/loader.conf:
geli_da0_keyfile0_load="YES"
geli_da0_keyfile0_type="da0:geli_keyfile0"
geli_da0_keyfile0_name="/boot/keys/da0.key0"
geli_da0_keyfile1_load="YES"
geli_da0_keyfile1_type="da0:geli_keyfile1"
geli_da0_keyfile1_name="/boot/keys/da0.key1"
geli_da0_keyfile2_load="YES"
geli_da0_keyfile2_type="da0:geli_keyfile2"
geli_da0_keyfile2_name="/boot/keys/da0.key2"
geli_da1s3a_keyfile0_load="YES"
geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
If there is only one keyfile, the index might be omitted:
geli_da1s3a_keyfile_load="YES"
geli_da1s3a_keyfile_type="da1s3a:geli_keyfile"
geli_da1s3a_keyfile_name="/boot/keys/da1s3a.key"
Not only configure encryption, but also data integrity verification using HMAC/SHA256.
# geli init -a hmac/sha256 -s 4096 /dev/da0
Enter new passphrase:
Reenter new passphrase:
# geli attach /dev/da0
Enter passphrase:
# dd if=/dev/random of=/dev/da0.eli bs=1m
# newfs /dev/da0.eli
# mount /dev/da0.eli /mnt/secret
geli writes the metadata backup by default to the /var/backups/_prov_.eli file. If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored. Consider the following situation:
# geli init /dev/da0
Enter new passphrase:
Reenter new passphrase:
Metadata backup can be found in /var/backups/da0.eli and
can be restored with the following command:
# geli restore /var/backups/da0.eli /dev/da0
# geli clear /dev/da0
# geli attach /dev/da0
geli: Cannot read metadata from /dev/da0: Invalid argument.
# geli restore /var/backups/da0.eli /dev/da0
# geli attach /dev/da0
Enter passphrase:
If an encrypted filesystem is extended, it is necessary to relocate and update the metadata:
# gpart create -s GPT ada0
# gpart add -s 1g -t freebsd-ufs -i 1 ada0
# geli init -K keyfile -P ada0p1
# gpart resize -s 2g -i 1 ada0
# geli resize -s 1g ada0p1
# geli attach -k keyfile -p ada0p1
Initialize provider with the passphrase split into two files. The provider can be attached using those two files or by entering "foobar" as the passphrase at the geli prompt:
# echo foo > da0.pass0
# echo bar > da0.pass1
# geli init -J da0.pass0 -J da0.pass1 da0
# geli attach -j da0.pass0 -j da0.pass1 da0
# geli detach da0
# geli attach da0
Enter passphrase: foobar
Suspend all geli devices on a laptop, suspend the laptop, then resume devices one by one after resuming the laptop:
# geli suspend -a
# zzz
# geli resume -p -k keyfile gpt/secret
# geli resume gpt/private
Enter passphrase:
ENCRYPTION MODES
geli supports two encryption modes: XTS, which was standardized as IEEE P1619 and CBC with unpredictable IV. The CBC mode used by geli is very similar to the mode ESSIV.
DATA AUTHENTICATION
geli can verify data integrity when an authentication algorithm is specified. When data corruption/modification is detected, geli will not return any data, but instead will return an error (EINVAL). The offset and size of the corrupted data will be printed on the console. It is important to know against which attacks geli provides protection for your data. If data is modified in-place or copied from one place on the disk to another even without modification, geli should be able to detect such a change. If an attacker can remember the encrypted data, he can overwrite any future changes with the data he owns without it being noticed. In other words geli will not protect your data against replay attacks.
It is recommended to write to the whole provider before first use, in order to make sure that all sectors and their corresponding checksums are properly initialized into a consistent state. One can safely ignore data authentication errors that occur immediately after the first time a provider is attached and before it is initialized in this way.
