NAME
cgdconfig —
configuration utility for
the cryptographic disk driver
SYNOPSIS
cgdconfig |
[-npv]
[-V vmeth]
cgd dev
[paramsfile] |
cgdconfig |
-C [-nv]
[-f
configfile] |
cgdconfig |
-G [-nv]
[-i
ivmeth]
[-k
kgmeth]
[-o
outfile]
paramsfile |
cgdconfig |
-g [-nv]
[-i
ivmeth]
[-k
kgmeth]
[-o
outfile] alg
[keylen] |
cgdconfig |
-s [-nv]
[-i
ivmeth] cgd
dev alg
[keylen] |
cgdconfig |
-U [-nv]
[-f
configfile] |
DESCRIPTION
cgdconfig is used to configure and unconfigure cryptographic
disk devices (cgds) and to maintain the configuration files that are
associated with them. For more information about cryptographic disk devices
see
cgd(4).
The options are as follows:
-
-
- -C
- Configure all the devices listed in the cgd configuration
file.
-
-
- -f
configfile
- Specify the configuration file explicitly, rather than
using the default configuration file
/etc/cgd/cgd.conf.
-
-
- -G
- Generate a new paramsfile (to stdout) using the values from
paramsfile which will generate the same key. This
may need to prompt for multiple passphrases.
-
-
- -g
- Generate a paramsfile (to stdout).
-
-
- -i
ivmeth
- Specify the IV method (default: encblkno1).
-
-
- -k
kgmeth
- Specify the key generation method (default:
pkcs5_pbkdf2/sha1).
-
-
- -l
[cgd]
- List state of all devices or just the one
cgd device. The verbosity level affects the
output.
-
-
- -n
- Do not actually configure or unconfigure a cryptographic
disk device, but instead report the steps that would be taken.
-
-
- -o
outfile
- When generating a paramsfile, store
it in outfile.
-
-
- -p
- Read all passphrases from stdin rather than
/dev/tty. Passphrases are separated by newlines. Users
of this flag must be able to predict the order in which passphrases are
prompted. If this flag is specified then verification errors will cause
the device in question to be unconfigured rather than prompting for the
passphrase again.
-
-
- -s
- Read the key from stdin.
-
-
- -U
- Unconfigure all the devices listed in the cgd configuration
file.
-
-
- -u
- Unconfigure a cgd.
-
-
- -V
vmeth
- Specify the verification method (default: none).
-
-
- -v
- Be verbose. May be specified multiple times.
For more information about the cryptographic algorithms and IV methods
supported, please refer to
cgd(4).
Key Generation Methods
To generate the key which it will use,
cgdconfig evaluates all
of the key generation methods in the parameters file and uses the exclusive-or
of the outputs of all the methods. The methods and descriptions are as
follows:
-
-
- pkcs5_pbkdf2/sha1
- This method requires a passphrase which is entered at
configuration time. It is a salted hmac-based scheme detailed in
“PKCS#5 v2.0: Password-Based Cryptography Standard”, RSA
Laboratories, March 25, 1999, pages 8-10. PKCS #5 was also republished as
RFC 2898.
-
-
- pkcs5_pbkdf2
- This is an earlier, slightly incorrect and deprecated
implementation of the above algorithm. It is retained for backwards
compatibility with existing parameters files, and will be removed.
Existing parameters files should be converted to use the correct method
using the -G option, and a new passphrase.
-
-
- storedkey
- This method stores its key in the parameters file.
-
-
- randomkey
- The method simply reads /dev/random and
uses the resulting bits as the key. It does not require a passphrase to be
entered. This method is typically used to present disk devices that do not
need to survive a reboot, such as the swap partition. It is also handy to
facilitate overwriting the contents of a disk volume with meaningless data
prior to use.
-
-
- urandomkey
- The method simply reads /dev/urandom and
uses the resulting bits as the key. This is similar to the
randomkey method, but it guarantees that cgdconfig will
not stall waiting for hard-random bits (useful when configuring a cgd for
swap at boot time). Note, however, that some or all of the bits used to
generate the key may be obtained from a pseudo-random number generator,
which may not be as secure as the entropy based hard-random number
generator.
-
-
- shell_cmd
- This method executes a shell command via
popen(3) and reads the key
from stdout.
Verification Method
The verification method is how
cgdconfig determines if the
generated key is correct. If the newly configured disk fails to verify, then
cgdconfig will regenerate the key and re-configure the
device. It only makes sense to specify a verification method if at least one
of the key generation methods is error prone, e.g., uses a user-entered
passphrase. The following verification methods are supported:
- none
- perform no verification.
- disklabel
- scan for a valid disklabel.
- mbr
- scan for a valid Master Boot Record.
- gpt
- scan for a valid GUID partition table.
- ffs
- scan for a valid FFS file system.
- re-enter
- prompt for passphrase twice, and ensure entered passphrases
are identical. This method only works with the pkcs5_pbkdf2/sha1 and
pkcs5_pbkdf2 key generators.
/etc/cgd/cgd.conf
The file
/etc/cgd/cgd.conf is used to configure
cgdconfig if either of
-C or
-U are specified. Each line of the file is composed of
either two or three tokens: cgd, target, and optional paramsfile.
A ‘#’ character is interpreted as a comment and indicates that the
rest of the line should be ignored. A ‘\’ at the end of a line
indicates that the next line is a continuation of the current line.
See
EXAMPLES for an example of
/etc/cgd/cgd.conf.
Parameters File
The Parameters File contains the required information to generate the key and
configure a device. These files are typically generated by the
-g flag and not edited by hand. When a device is configured
the default parameters file is constructed by taking the basename of the
target disk and prepending
/etc/cgd/ to it. E.g., if the
target is
/dev/sd0h, then the default parameters file will
be
/etc/cgd/sd0h.
It is possible to have more than one parameters file for a given disk which use
different key generation methods but will generate the same key. To create a
parameters file that is equivalent to an existing parameters file, use
cgdconfig with the
-G flag. See
EXAMPLES for an example of this usage.
The parameters file contains a list of statements each terminated with a
semi-colon. Some statements can contain statement-blocks which are either a
single unadorned statement, or a brace-enclosed list of semicolon terminated
statements. Three types of data are understood:
- integer
- a 32 bit signed integer.
- string
- a string.
- base64
- a length-encoded base64 string.
The following statements are defined:
-
-
- algorithm
string
- Defines the cryptographic algorithm.
-
-
- iv-method
string
- Defines the IV generation method.
-
-
- keylength
integer
- Defines the length of the key.
-
-
- verify_method
string
- Defines the verification method.
-
-
- keygen
string statement_block
- Defines a key generation method. The
statement_block contains statements that are
specific to the key generation method.
The keygen statement's statement block may contain the following statements:
-
-
- key
string
- The key. Only used for the storedkey key generation
method.
-
-
- cmd
string
- The command to execute. Only used for the shell_cmd key
generation method.
-
-
- iterations
integer
- The number of iterations. Only used for pkcs5_pbkdf2/sha1
and pkcs5_pbkdf2.
-
-
- salt
base64
- The salt. Only used for pkcs5_pbkdf2/sha1 and
pkcs5_pbkdf2.
FILES
- /etc/cgd/
- configuration directory, used to store paramsfiles.
- /etc/cgd/cgd.conf
- cgd configuration file.
EXAMPLES
To set up and configure a cgd that uses AES with a 192 bit key in CBC mode with
the IV Method ‘encblkno1’ (encrypted block number):
# cgdconfig -g -o /etc/cgd/wd0e aes-cbc 192
# cgdconfig cgd0 /dev/wd0e
/dev/wd0e's passphrase:
When using verification methods, the first time that we configure the disk the
verification method will fail. We overcome this by supplying
-V re-enter when we configure the
first time to set up the disk. Here is the sequence of commands that is
recommended:
# cgdconfig -g -o /etc/cgd/wd0e -V disklabel aes-cbc
# cgdconfig -V re-enter cgd0 /dev/wd0e
/dev/wd0e's passphrase:
re-enter device's passphrase:
# disklabel -e -I cgd0
# cgdconfig -u cgd0
# cgdconfig cgd0 /dev/wd0e
/dev/wd0e's passphrase:
To scrub data from a disk before setting up a cgd:
# cgdconfig -s cgd0 /dev/sd0e aes-cbc 256 < /dev/urandom
# dd if=/dev/zero of=/dev/rcgd0d bs=32k progress=512
# cgdconfig -u cgd0
To create a new parameters file that will generate the same key as an old
parameters file:
# cgdconfig -G -o newparamsfile oldparamsfile
old file's passphrase:
new file's passphrase:
To configure a cgd that uses Blowfish with a 200 bit key that it reads from
stdin:
# cgdconfig -s cgd0 /dev/sd0h blowfish-cbc 200
An example parameters file which uses PKCS#5 PBKDF2:
algorithm aes-cbc;
iv-method encblkno1;
keylength 128;
verify_method none;
keygen pkcs5_pbkdf2/sha1 {
iterations 39361;
salt AAAAgMoHiYonye6Kog \
dYJAobCHE=;
};
An example parameters file which stores its key locally:
algorithm aes-cbc;
iv-method encblkno1;
keylength 256;
verify_method none;
keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \
ly2TdxkFqOkYYcbyUKu/f60L;
An example
/etc/cgd/cgd.conf:
#
# /etc/cgd/cgd.conf
# Configuration file for cryptographic disk devices
#
# cgd target [paramsfile]
cgd0 /dev/wd0e
cgd1 /dev/sd0h /usr/local/etc/cgd/sd0h
Note the first entry will store the parameters file as
/etc/cgd/wd0e. And use the entered passphrase to generate
the key.
Although not required, the partition type
cgd should be
used in the disklabel for the cgd partition.
DIAGNOSTICS
- cgdconfig: could not calibrate
pkcs5_pbkdf2
- An error greater than 5% in calibration occurred. This
could be the result of dynamic processor frequency scaling technology.
Ensure that the processor clock frequency remains static throughout the
program's execution.
SEE ALSO
cgd(4)
“PKCS #5 v2.0: Password-Based Cryptography Standard”, RSA
Laboratories, March 25, 1999.
HISTORY
The
cgdconfig utility appeared in
NetBSD
2.0.
BUGS
Since
cgdconfig uses
getpass(3) to read in the
passphrase, it is limited to 128 characters.