kdb5_util

- Kerberos Database maintenance utility

Synopsis

/usr/sbin/kdb5_util [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-m ]
     [-M mkeyname] [-P password] [-r realm] [-sf stashfilename]
     [-x db_args]... cmd

Description

The kdb5_util utility enables you to create, dump, load, and destroy the Kerberos V5 database. You can also use kdb5_util to create a stash file containing the Kerberos database master key.

Options

The following options are supported:

-d dbname

Specify the database name. .db is appended to whatever name is specified. You can specify an absolute path. If you do not specify the -d option, the default database name is /var/krb5/principal.

-k mkeytype

Specify the master key type. Valid values are des3-cbc-sha1, des-cbc-crc, des-cbc-md5, des-cbc-raw, arcfour-hmac-md5, arcfour-hmac-md5-exp, aes128-cts-hmac-sha1-96, and aes256-cts-hmac-sha1-96.

-m

Enter the master key manually.

-M mkeyname

Specify the master key name.

-P password

Use the specified password instead of the stash file.

-r realm

Use realm as the default database realm.

-sf stashfile_name

Specifies the stash file of the master database password.

-x db_args

Pass database-specific arguments to kadmin. Supported arguments are for LDAP and the Berkeley-db2 plug-in. These arguments are:

binddn=binddn

LDAP simple bind DN for authorization on the directory server. Overrides the ldap_kadmind_dn parameter setting in krb5.conf(4).

bindpwd=bindpwd

Bind password.

dbname=name

For the Berkeley-db2 plug-in, specifies a name for the Kerberos database.

nconns=num

Maximum number of server connections.

port=num

Directory server connection port.

Operands

The following operands are supported:

cmd

Specifies whether to create, destroy, dump, or load the database, or to create a stash file.

You can specify the following commands:

create -s

Creates the database specified by the -d option. You will be prompted for the database master password. If you specify -s, a stash file is created as specified by the -f option. If you did not specify -f, the default stash file name is /var/krb5/.k5.realm. If you use the -f, -k, or -M options when you create a database, then you must use the same options when modifying or destroying the database.

destroy

Destroys the database specified by the -d option.

stash

Creates a stash file. If -f was not specified, the default stash file name is /var/krb5/.k5.realm. You will be prompted for the master database password. This command is useful when you want to generate the stash file from the password.

dump [-old] [-b6] [-b7] [-ov] [-r13] [-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_dumpversion 6”. If filename is not specified or is the string “-”, the dump is sent to standard output. Options are as follows:

-old

Causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format (“kdb5_edit load_dump version 2.0”).

-b6

Causes the dump to be in the Kerberos 5 Beta 6 format (“kdb5_edit load_dump version 3.0”).

-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.

-ov

Causes the dump to be in ovsec_adm_export format.

-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.

-verbose

Causes the name of each principal and policy to be displayed as it is dumped.

-mkey_convert

Prompts for a new master key. This new master key will be used to re-encrypt the key data in the dumpfile. The key data in the database 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 might recover principals that do not dump normally, in cases where database corruption has occured.

-recurse

Causes the dump to walk the database recursively (btree only). This might 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 will the -rev option.

load [-old] [-b6] [-b7] [-ov] [-r13] [-hash] [-verbose] [-update] filename dbname [admin_dbname]

Loads a database dump from filename into dbname. Unless the -old or -b6 option is specified, the format of the dump file is detected automatically and handled appropriately. Unless the -update option is specified, load creates a new database containing only the principals in the dump file, overwriting the contents of any existing database. The -old option requires the database to be in the Kerberos 5 Beta 5 or earlier format (“kdb5_edit load_dump version 2.0”).

-b6

Requires the database to be in the Kerberos 5 Beta 6 format (“kdb5_edit load_dump version 3.0”).

-b7

Requires the database to be in the Kerberos 5 Beta 7 format (“kdb5_util load_dump version 4”).

-ov

Requires the database to be in ovsec_adm_import format. Must be used with the -update option.

-hash

Requires the database to be stored as a hash. If this option is not specified, the database will be stored as a btree. This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals.

-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.

-verbose

Causes the name of each principal and policy to be displayed 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 is destroyed upon successful completion.

filename

Required argument that specifies a path to a file containing database dump.

dbname

Required argument that overrides the value specified on the command line or overrides the default.

admin_dbname

Optional argument that is derived from dbname if not specified.

add_mkey [-e etype] [-s]

Adds a new master key to the K/M (master key) principal. Existing master keys will remain. The -e etype option allows specification of the enctype of the new master key. The -s option stashes the new master key in a local stash file which will be created if it does not already exist.

use_mkey mkeyVNO [time]

Sets the activation time of the master key specified by mkeyVNO. Once a master key is active (that is, its activation time has been reached) it will then be used to encrypt principal keys either when the principal keys change, are newly created, or when the update_princ_encryption command is run. If the time argument is provided, that will be the activation time; otherwise the current time is used by default. The format of the optional time argument is that specified in the Time Formats section of the kadmin(1M) man page.

list_mkeys

List all master keys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey, similar to kadmin getprinc output. An asterisk (*) following an mkey denotes the currently active master key.

purge_mkeys [-f] [-n] [-v]

Delete master keys from the K/M principal that are not used to protect any principals. This command can be used to remove old master keys from a K/M principal once all principal keys are protected by a newer master key.

-f

Does not prompt user.

-n

Does a dry run, shows master keys that would be purged, but does not actually purge any keys.

-v

Verbose output.

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 older versions, 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 (each one matching the pattern) to be listed, and an indication given as to whether it needed updating or not. The -n option causes the actions not to be taken, only the normal or verbose status messages displayed; this implies -f, since no database changes will be performed and thus there is little reason to seek confirmation.

Examples

Example 1 Creating File that Contains Information about Two Principals

The following example creates a file named slavedata that contains the information about two principals, jdb@ACME.COM and pak@ACME.COM.

# /usr/krb5/bin/kdb5_util dump -verbose slavedata
jdb@ACME.COM pak@ACME.COM

Files

/var/krb5/principal

Kerberos principal database.

/var/krb5/principal.kadm5

Kerberos administrative database. Contains policy information.

/var/krb5/principal.kadm5.lock

Lock file for the Kerberos administrative database. This file works backwards from most other lock files (that is, kadmin exits with an error if this file does not exist).

/var/krb5/principal.ulog

The update log file for incremental propagation.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

kpasswd(1), gkadmin(1M), kadmin(1M), kadmind(1M), kadmin.local(1M), kdb5_ldap_util(1M), kproplog(1M), kadm5.acl(4), kdc.conf(4), attributes(5), kerberos(5)

Notes

The global -f is made obsolete with the -sf argument for specifying a non-default stash file location. The global -f argument might be removed in a future release of the Solaris operating system. Use caution in specifying -f as it has different semantics in subcommands as distinguished from its use as a global argument.