kdb5_util - Kerberos database maintenance utility
kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M mkey- name] [-m] [-sf stashfilename] [-P password] [-x db_args] command [com- mand_options]
KDB5_UTIL(8) MIT Kerberos KDB5_UTIL(8)
NAME
kdb5_util - Kerberos database maintenance utility
SYNOPSIS
kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M mkey-
name] [-m] [-sf stashfilename] [-P password] [-x db_args] command [com-
mand_options]
DESCRIPTION
kdb5_util allows an administrator to perform maintenance procedures on
the KDC database. Databases can be created, destroyed, and dumped to
or loaded from ASCII files. kdb5_util can create a Kerberos master key
stash file or perform live rollover of the master key.
When kdb5_util is run, it attempts to acquire the master key and open
the database. However, execution continues regardless of whether or
not kdb5_util successfully opens the database, because the database may
not exist yet or the stash file may be corrupt.
Note that some KDC database modules may not support all kdb5_util com-
mands.
COMMAND-LINE OPTIONS
-r realm
specifies the Kerberos realm of the database.
-d dbname
specifies the name under which the principal database is stored;
by default the database is that listed in kdc.conf(5). The
password policy database and lock files are also derived from
this value.
-k mkeytype
specifies the key type of the master key in the database. The
default is given by the master_key_type variable in kdc.conf(5).
-kv mkeyVNO
Specifies the version number of the master key in the database;
the default is 1. Note that 0 is not allowed.
-M mkeyname
principal name for the master key in the database. If not spec-
ified, the name is determined by the master_key_name variable in
kdc.conf(5).
-m specifies that the master database password should be read from
the keyboard rather than fetched from a file on disk.
-sf stash_file
specifies the stash filename of the master database password.
If not specified, the filename is determined by the
key_stash_file variable in kdc.conf(5).
-P password
specifies the master database password. Using this option may
expose the password to other users on the system via the process
list.
-x db_args
specifies database-specific options. See kadmin(1) for sup-
ported options.
COMMANDS
create
create [-s]
Creates a new database. If the -s option is specified, the stash file
is also created. This command fails if the database already exists.
If the command is successful, the database is opened just as if it had
already existed when the program was first run.
destroy
destroy [-f]
Destroys the database, first overwriting the disk sectors and then
unlinking the files, after prompting the user for confirmation. With
the -f argument, does not prompt the user.
stash
stash [-f keyfile]
Stores the master principal's keys in a stash file. The -f argument
can be used to override the keyfile specified in kdc.conf(5).
dump
dump [-b7|-r13|-r18] [-verbose] [-mkey_convert] [-new_mkey_file
mkey_file] [-rev] [-recurse] [filename [principals...]]
Dumps the current Kerberos and KADM5 database into an ASCII file. By
default, the database is dumped in current format, "kdb5_util load_dump
version 7". If filename is not specified, or is the string "-", the
dump is sent to standard output. Options:
-b7 causes the dump to be in the Kerberos 5 Beta 7 format
("kdb5_util load_dump version 4"). This was the dump format
produced on releases prior to 1.2.2.
-r13 causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util
load_dump version 5"). This was the dump format produced on
releases prior to 1.8.
-r18 causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util
load_dump version 6"). This was the dump format produced on
releases prior to 1.11.
-verbose
causes the name of each principal and policy to be printed as it
is dumped.
-mkey_convert
prompts for a new master key. This new master key will be used
to re-encrypt principal key data in the dumpfile. The principal
keys themselves will not be changed.
-new_mkey_file mkey_file
the filename of a stash file. The master key in this stash file
will be used to re-encrypt the key data in the dumpfile. The
key data in the database will not be changed.
-rev dumps in reverse order. This may recover principals that do not
dump normally, in cases where database corruption has occurred.
-recurse
causes the dump to walk the database recursively (btree only).
This may recover principals that do not dump normally, in cases
where database corruption has occurred. In cases of such cor-
ruption, this option will probably retrieve more principals than
the -rev option will.
Changed in version 1.15: Release 1.15 restored the functionality
of the -recurse option.
Changed in version 1.5: The -recurse option ceased working until
release 1.15, doing a normal dump instead of a recursive traver-
sal.
load
load [-b7|-r13|-r18] [-hash] [-verbose] [-update] filename
Loads a database dump from the named file into the named database. If
no option is given to determine the format of the dump file, the format
is detected automatically and handled as appropriate. Unless the
-update option is given, load creates a new database containing only
the data in the dump file, overwriting the contents of any previously
existing database. Note that when using the LDAP KDC database module,
the -update flag is required.
Options:
-b7 requires the database to be in the Kerberos 5 Beta 7 format
("kdb5_util load_dump version 4"). This was the dump format
produced on releases prior to 1.2.2.
-r13 requires the database to be in Kerberos 5 1.3 format ("kdb5_util
load_dump version 5"). This was the dump format produced on
releases prior to 1.8.
-r18 requires the database to be in Kerberos 5 1.8 format ("kdb5_util
load_dump version 6"). This was the dump format produced on
releases prior to 1.11.
-hash stores the database in hash format, if using the DB2 database
type. If this option is not specified, the database will be
stored in btree format. This option is not recommended, as
databases stored in hash format are known to corrupt data and
lose principals.
-verbose
causes the name of each principal and policy to be printed as it
is dumped.
-update
records from the dump file are added to or updated in the exist-
ing database. Otherwise, a new database is created containing
only what is in the dump file and the old one destroyed upon
successful completion.
ark
ark [-e enc:salt,...] principal
Adds new random keys to principal at the next available key version
number. Keys for the current highest key version number will be pre-
served. The -e option specifies the list of encryption and salt types
to be used for the new keys.
add_mkey
add_mkey [-e etype] [-s]
Adds a new master key to the master key principal, but does not mark it
as active. Existing master keys will remain. The -e option specifies
the encryption type of the new master key; see Encryption_types in
kdc.conf(5) for a list of possible values. The -s option stashes the
new master key in the stash file, which will be created if it doesn't
already exist.
After a new master key is added, it should be propagated to replica
servers via a manual or periodic invocation of kprop(8). Then, the
stash files on the replica servers should be updated with the kdb5_util
stash command. Once those steps are complete, the key is ready to be
marked active with the kdb5_util use_mkey command.
use_mkey
use_mkey mkeyVNO [time]
Sets the activation time of the master key specified by mkeyVNO. Once
a master key becomes active, it will be used to encrypt newly created
principal keys. If no time argument is given, the current time is
used, causing the specified master key version to become active immedi-
ately. The format for time is getdate string.
After a new master key becomes active, the kdb5_util
update_princ_encryption command can be used to update all principal
keys to be encrypted in the new master key.
list_mkeys
list_mkeys
List all master keys, from most recent to earliest, in the master key
principal. The output will show the kvno, enctype, and salt type for
each mkey, similar to the output of kadmin(1) getprinc. A * following
an mkey denotes the currently active master key.
purge_mkeys
purge_mkeys [-f] [-n] [-v]
Delete master keys from the master key principal that are not used to
protect any principals. This command can be used to remove old master
keys all principal keys are protected by a newer master key.
-f does not prompt for confirmation.
-n performs a dry run, showing master keys that would be purged,
but not actually purging any keys.
-v gives more verbose output.
update_princ_encryption
update_princ_encryption [-f] [-n] [-v] [princ-pattern]
Update all principal records (or only those matching the princ-pattern
glob pattern) to re-encrypt the key data using the active database mas-
ter key, if they are encrypted using a different version, and give a
count at the end of the number of principals updated. If the -f option
is not given, ask for confirmation before starting to make changes.
The -v option causes each principal processed to be listed, with an
indication as to whether it needed updating or not. The -n option per-
forms a dry run, only showing the actions which would have been taken.
tabdump
tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
Dump selected fields of the database in a tabular format suitable for
reporting (e.g., using traditional Unix text processing tools) or
importing into relational databases. The data format is tab-separated
(default), or optionally comma-separated (CSV), with a fixed number of
columns. The output begins with a header line containing field names,
unless suppression is requested using the -H option.
The dumptype parameter specifies the name of an output table (see
below).
Options:
-H suppress writing the field names in a header line
-c use comma separated values (CSV) format, with minimal quoting,
instead of the default tab-separated (unquoted, unescaped) for-
mat
-e write empty hexadecimal string fields as empty fields instead of
as "-1".
-n produce numeric output for fields that normally have symbolic
output, such as enctypes and flag names. Also requests output
of time stamps as decimal POSIX time_t values.
-o outfile
write the dump to the specified output file instead of to stan-
dard output
Dump types:
keydata
principal encryption key information, including actual key data
(which is still encrypted in the master key)
name principal name
keyindex
index of this key in the principal's key list
kvno key version number
enctype
encryption type
key key data as a hexadecimal string
salttype
salt type
salt salt data as a hexadecimal string
keyinfo
principal encryption key information (as in keydata above),
excluding actual key data
princ_flags
principal boolean attributes. Flag names print as hexadecimal
numbers if the -n option is specified, and all flag positions
are printed regardless of whether or not they are set. If -n is
not specified, print all known flag names for each principal,
but only print hexadecimal flag names if the corresponding flag
is set.
name principal name
flag flag name
value boolean value (0 for clear, or 1 for set)
princ_lockout
state information used for tracking repeated password failures
name principal name
last_success
time stamp of most recent successful authentication
last_failed
time stamp of most recent failed authentication
fail_count
count of failed attempts
princ_meta
principal metadata
name principal name
modby name of last principal to modify this principal
modtime
timestamp of last modification
lastpwd
timestamp of last password change
policy policy object name
mkvno key version number of the master key that encrypts this
principal's key data
hist_kvno
key version number of the history key that encrypts the
key history data for this principal
princ_stringattrs
string attributes (key/value pairs)
name principal name
key attribute name
value attribute value
princ_tktpolicy
per-principal ticket policy data, including maximum ticket life-
times
name principal name
expiration
principal expiration date
pw_expiration
password expiration date
max_life
maximum ticket lifetime
max_renew_life
maximum renewable ticket lifetime
Examples:
$ kdb5_util tabdump -o keyinfo.txt keyinfo
$ cat keyinfo.txt
name keyindex kvno enctype salttype salt
K/M@EXAMPLE.COM 0 1 aes256-cts-hmac-sha384-192 normal -1
foo@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
bar@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
$ sqlite3
sqlite> .mode tabs
sqlite> .import keyinfo.txt keyinfo
sqlite> select * from keyinfo where enctype like 'aes256-%';
K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1
sqlite> .quit
$ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1
ENVIRONMENT
See kerberos(7) for a description of Kerberos environment variables.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+-------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------------+
|Availability | security/kerberos-5/kdc |
+---------------+-------------------------+
|Stability | Pass-through committed |
+---------------+-------------------------+
SEE ALSO
kadmin(1), kerberos(7)
AUTHOR
MIT
COPYRIGHT
1985-2021, MIT
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://web.mit.edu/ker-
beros/dist/krb5/1.18/krb5-1.18.4.tar.gz.
Further information about this software can be found on the open source
community website at http://web.mit.edu/kerberos/.
1.18.4 KDB5_UTIL(8)