Ubuntu Manpage: kdb5_util - Kerberos database maintenance utility

Provided by: krb5-kdc_1.20.1-6ubuntu2.1_amd64

NAME

       kdb5_util - Kerberos database maintenance utility

SYNOPSIS

       kdb5_util  [-r  realm]  [-d  dbname]  [-k  mkeytype] [-kv mkeyVNO] [-M mkeyname] [-m] [-sf
       stashfilename] [-P password] [-x db_args] command [command_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 commands.

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 specified, 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 supported 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 corruption, 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 traversal.

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 existing 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 preserved. 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 immediately. 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 master 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 performs 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) format

-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 standard 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 lifetimes

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.

AUTHOR

MIT

COPYRIGHT

       1985-2022, MIT

NAME

SYNOPSIS

DESCRIPTION

COMMAND-LINE OPTIONS

COMMANDS

ENVIRONMENT

SEE ALSO

AUTHOR

COPYRIGHT