1KDB5_UTIL(8)                     MIT Kerberos                     KDB5_UTIL(8)
2
3
4

NAME

6       kdb5_util - Kerberos database maintenance utility
7

SYNOPSIS

9       kdb5_util  [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M mkey‐
10       name] [-m] [-sf stashfilename] [-P password] [-x db_args] command [com‐
11       mand_options]
12

DESCRIPTION

14       kdb5_util  allows an administrator to perform maintenance procedures on
15       the KDC database.  Databases can be created, destroyed, and  dumped  to
16       or loaded from ASCII files.  kdb5_util can create a Kerberos master key
17       stash file or perform live rollover of the master key.
18
19       When kdb5_util is run, it attempts to acquire the master key  and  open
20       the  database.   However,  execution continues regardless of whether or
21       not kdb5_util successfully opens the database, because the database may
22       not exist yet or the stash file may be corrupt.
23
24       Note  that some KDC database modules may not support all kdb5_util com‐
25       mands.
26

COMMAND-LINE OPTIONS

28       -r realm
29              specifies the Kerberos realm of the database.
30
31       -d dbname
32              specifies the name under which the principal database is stored;
33              by  default  the database is that listed in kdc.conf.  The pass‐
34              word policy database and lock files are also derived  from  this
35              value.
36
37       -k mkeytype
38              specifies  the  key type of the master key in the database.  The
39              default is given by the master_key_type variable in kdc.conf.
40
41       -kv mkeyVNO
42              Specifies the version number of the master key in the  database;
43              the default is 1.  Note that 0 is not allowed.
44
45       -M mkeyname
46              principal name for the master key in the database.  If not spec‐
47              ified, the name is determined by the master_key_name variable in
48              kdc.conf.
49
50       -m     specifies  that the master database password should be read from
51              the keyboard rather than fetched from a file on disk.
52
53       -sf stash_file
54              specifies the stash filename of the  master  database  password.
55              If   not   specified,   the   filename   is  determined  by  the
56              key_stash_file variable in kdc.conf.
57
58       -P password
59              specifies the master database password.  Using this  option  may
60              expose the password to other users on the system via the process
61              list.
62
63       -x db_args
64              specifies database-specific options.  See kadmin  for  supported
65              options.
66

COMMANDS

68   create
69          create [-s]
70
71       Creates  a new database.  If the -s option is specified, the stash file
72       is also created.  This command fails if the  database  already  exists.
73       If  the command is successful, the database is opened just as if it had
74       already existed when the program was first run.
75
76   destroy
77          destroy [-f]
78
79       Destroys the database, first overwriting the disk sectors and then  un‐
80       linking the files, after prompting the user for confirmation.  With the
81       -f argument, does not prompt the user.
82
83   stash
84          stash [-f keyfile]
85
86       Stores the master principal's keys in a stash file.   The  -f  argument
87       can be used to override the keyfile specified in kdc.conf.
88
89   dump
90          dump   [-b7|-r13|-r18]  [-verbose]  [-mkey_convert]  [-new_mkey_file
91          mkey_file] [-rev] [-recurse] [filename [principals...]]
92
93       Dumps the current Kerberos and KADM5 database into an ASCII  file.   By
94       default, the database is dumped in current format, "kdb5_util load_dump
95       version 7".  If filename is not specified, or is the  string  "-",  the
96       dump is sent to standard output.  Options:
97
98       -b7    causes  the  dump  to  be  in  the  Kerberos  5  Beta  7  format
99              ("kdb5_util load_dump version 4").  This  was  the  dump  format
100              produced on releases prior to 1.2.2.
101
102       -r13   causes  the  dump to be in the Kerberos 5 1.3 format ("kdb5_util
103              load_dump version 5").  This was the dump format produced on re‐
104              leases prior to 1.8.
105
106       -r18   causes  the  dump to be in the Kerberos 5 1.8 format ("kdb5_util
107              load_dump version 6").  This was the dump format produced on re‐
108              leases prior to 1.11.
109
110       -verbose
111              causes the name of each principal and policy to be printed as it
112              is dumped.
113
114       -mkey_convert
115              prompts for a new master key.  This new master key will be  used
116              to re-encrypt principal key data in the dumpfile.  The principal
117              keys themselves will not be changed.
118
119       -new_mkey_file mkey_file
120              the filename of a stash file.  The master key in this stash file
121              will  be  used  to re-encrypt the key data in the dumpfile.  The
122              key data in the database will not be changed.
123
124       -rev   dumps in reverse order.  This may recover principals that do not
125              dump normally, in cases where database corruption has occurred.
126
127       -recurse
128              causes  the  dump to walk the database recursively (btree only).
129              This may recover principals that do not dump normally, in  cases
130              where  database  corruption has occurred.  In cases of such cor‐
131              ruption, this option will probably retrieve more principals than
132              the -rev option will.
133
134              Changed in version 1.15: Release 1.15 restored the functionality
135              of the -recurse option.
136
137
138              Changed in version 1.5: The -recurse option ceased working until
139              release 1.15, doing a normal dump instead of a recursive traver‐
140              sal.
141
142
143   load
144          load [-b7|-r13|-r18] [-hash] [-verbose] [-update] filename
145
146       Loads a database dump from the named file into the named database.   If
147       no option is given to determine the format of the dump file, the format
148       is detected automatically and handled as appropriate.  Unless the  -up‐
149       date  option  is given, load creates a new database containing only the
150       data in the dump file, overwriting the contents of any  previously  ex‐
151       isting  database.   Note  that when using the LDAP KDC database module,
152       the -update flag is required.
153
154       Options:
155
156       -b7    requires the database to be in the  Kerberos  5  Beta  7  format
157              ("kdb5_util  load_dump  version  4").   This was the dump format
158              produced on releases prior to 1.2.2.
159
160       -r13   requires the database to be in Kerberos 5 1.3 format ("kdb5_util
161              load_dump version 5").  This was the dump format produced on re‐
162              leases prior to 1.8.
163
164       -r18   requires the database to be in Kerberos 5 1.8 format ("kdb5_util
165              load_dump version 6").  This was the dump format produced on re‐
166              leases prior to 1.11.
167
168       -hash  stores the database in hash format, if using  the  DB2  database
169              type.   If  this  option  is not specified, the database will be
170              stored in btree format.  This  option  is  not  recommended,  as
171              databases  stored  in  hash format are known to corrupt data and
172              lose principals.
173
174       -verbose
175              causes the name of each principal and policy to be printed as it
176              is dumped.
177
178       -update
179              records from the dump file are added to or updated in the exist‐
180              ing database.  Otherwise, a new database is  created  containing
181              only  what  is  in  the dump file and the old one destroyed upon
182              successful completion.
183
184   ark
185          ark [-e enc:salt,...] principal
186
187       Adds new random keys to principal at the  next  available  key  version
188       number.   Keys  for the current highest key version number will be pre‐
189       served.  The -e option specifies the list of encryption and salt  types
190       to be used for the new keys.
191
192   add_mkey
193          add_mkey [-e etype] [-s]
194
195       Adds a new master key to the master key principal, but does not mark it
196       as active.  Existing master keys will remain.  The -e option  specifies
197       the  encryption  type  of  the  new master key; see Encryption types in
198       kdc.conf for a list of possible values.  The -s option stashes the  new
199       master  key  in the stash file, which will be created if it doesn't al‐
200       ready exist.
201
202       After a new master key is added, it should  be  propagated  to  replica
203       servers  via a manual or periodic invocation of kprop.  Then, the stash
204       files on the replica servers should be updated with the kdb5_util stash
205       command.   Once those steps are complete, the key is ready to be marked
206       active with the kdb5_util use_mkey command.
207
208   use_mkey
209          use_mkey mkeyVNO [time]
210
211       Sets the activation time of the master key specified by mkeyVNO.   Once
212       a  master  key becomes active, it will be used to encrypt newly created
213       principal keys.  If no time argument is  given,  the  current  time  is
214       used, causing the specified master key version to become active immedi‐
215       ately.  The format for time is getdate time string.
216
217       After a new master key becomes active, the  kdb5_util  update_princ_en‐
218       cryption  command  can  be  used to update all principal keys to be en‐
219       crypted in the new master key.
220
221   list_mkeys
222          list_mkeys
223
224       List all master keys, from most recent to earliest, in the  master  key
225       principal.   The  output will show the kvno, enctype, and salt type for
226       each mkey, similar to the output of kadmin getprinc.  A * following  an
227       mkey denotes the currently active master key.
228
229   purge_mkeys
230          purge_mkeys [-f] [-n] [-v]
231
232       Delete  master  keys from the master key principal that are not used to
233       protect any principals.  This command can be used to remove old  master
234       keys all principal keys are protected by a newer master key.
235
236       -f     does not prompt for confirmation.
237
238       -n     performs  a  dry  run, showing master keys that would be purged,
239              but not actually purging any keys.
240
241       -v     gives more verbose output.
242
243   update_princ_encryption
244          update_princ_encryption [-f] [-n] [-v] [princ-pattern]
245
246       Update all principal records (or only those matching the  princ-pattern
247       glob pattern) to re-encrypt the key data using the active database mas‐
248       ter key, if they are encrypted using a different version,  and  give  a
249       count at the end of the number of principals updated.  If the -f option
250       is not given, ask for confirmation before  starting  to  make  changes.
251       The -v option causes each principal processed to be listed, with an in‐
252       dication as to whether it needed updating or not.  The -n  option  per‐
253       forms a dry run, only showing the actions which would have been taken.
254
255   tabdump
256          tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
257
258       Dump  selected  fields of the database in a tabular format suitable for
259       reporting (e.g., using traditional Unix text processing tools)  or  im‐
260       porting  into  relational  databases.  The data format is tab-separated
261       (default), or optionally comma-separated (CSV), with a fixed number  of
262       columns.   The output begins with a header line containing field names,
263       unless suppression is requested using the -H option.
264
265       The dumptype parameter specifies the name of an output table  (see  be‐
266       low).
267
268       Options:
269
270       -H     suppress writing the field names in a header line
271
272       -c     use  comma  separated values (CSV) format, with minimal quoting,
273              instead of the default tab-separated (unquoted, unescaped)  for‐
274              mat
275
276       -e     write empty hexadecimal string fields as empty fields instead of
277              as "-1".
278
279       -n     produce numeric output for fields that  normally  have  symbolic
280              output,  such  as enctypes and flag names.  Also requests output
281              of time stamps as decimal POSIX time_t values.
282
283       -o outfile
284              write the dump to the specified output file instead of to  stan‐
285              dard output
286
287       Dump types:
288
289       keydata
290              principal  encryption key information, including actual key data
291              (which is still encrypted in the master key)
292
293              name   principal name
294
295              keyindex
296                     index of this key in the principal's key list
297
298              kvno   key version number
299
300              enctype
301                     encryption type
302
303              key    key data as a hexadecimal string
304
305              salttype
306                     salt type
307
308              salt   salt data as a hexadecimal string
309
310       keyinfo
311              principal encryption key information (as in keydata above),  ex‐
312              cluding actual key data
313
314       princ_flags
315              principal  boolean  attributes.  Flag names print as hexadecimal
316              numbers if the -n option is specified, and  all  flag  positions
317              are printed regardless of whether or not they are set.  If -n is
318              not specified, print all known flag names  for  each  principal,
319              but  only print hexadecimal flag names if the corresponding flag
320              is set.
321
322              name   principal name
323
324              flag   flag name
325
326              value  boolean value (0 for clear, or 1 for set)
327
328       princ_lockout
329              state information used for tracking repeated password failures
330
331              name   principal name
332
333              last_success
334                     time stamp of most recent successful authentication
335
336              last_failed
337                     time stamp of most recent failed authentication
338
339              fail_count
340                     count of failed attempts
341
342       princ_meta
343              principal metadata
344
345              name   principal name
346
347              modby  name of last principal to modify this principal
348
349              modtime
350                     timestamp of last modification
351
352              lastpwd
353                     timestamp of last password change
354
355              policy policy object name
356
357              mkvno  key version number of the master key that  encrypts  this
358                     principal's key data
359
360              hist_kvno
361                     key  version  number of the history key that encrypts the
362                     key history data for this principal
363
364       princ_stringattrs
365              string attributes (key/value pairs)
366
367              name   principal name
368
369              key    attribute name
370
371              value  attribute value
372
373       princ_tktpolicy
374              per-principal ticket policy data, including maximum ticket life‐
375              times
376
377              name   principal name
378
379              expiration
380                     principal expiration date
381
382              pw_expiration
383                     password expiration date
384
385              max_life
386                     maximum ticket lifetime
387
388              max_renew_life
389                     maximum renewable ticket lifetime
390
391       Examples:
392
393          $ kdb5_util tabdump -o keyinfo.txt keyinfo
394          $ cat keyinfo.txt
395          name        keyindex        kvno    enctype salttype        salt
396          K/M@EXAMPLE.COM     0       1       aes256-cts-hmac-sha384-192      normal  -1
397          foo@EXAMPLE.COM     0       1       aes128-cts-hmac-sha1-96 normal  -1
398          bar@EXAMPLE.COM     0       1       aes128-cts-hmac-sha1-96 normal  -1
399          $ sqlite3
400          sqlite> .mode tabs
401          sqlite> .import keyinfo.txt keyinfo
402          sqlite> select * from keyinfo where enctype like 'aes256-%';
403          K/M@EXAMPLE.COM     1       1       aes256-cts-hmac-sha384-192      normal  -1
404          sqlite> .quit
405          $ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
406          K/M@EXAMPLE.COM     1       1       aes256-cts-hmac-sha384-192      normal  -1
407

ENVIRONMENT

409       See kerberos for a description of Kerberos environment variables.
410

SEE ALSO

412       kadmin, kerberos
413

AUTHOR

415       MIT
416
418       1985-2023, MIT
419
420
421
422
4231.21.2                                                            KDB5_UTIL(8)
Impressum