NAME¶
wa_keyring - WebAuth keyring manipulation tool
SYNOPSIS¶
wa_keyring [
-hv]
-f file command [
arg
...]
wa_keyring -f keyring add
valid-after
wa_keyring -f keyring gc
oldest-valid-after-to-keep
wa_keyring -f keyring list
wa_keyring -f keyring remove
id
DESCRIPTION¶
wa_keyring is a command line tool to manage WebAuth key ring files, which
contain the private AES keys used by mod_webauth and mod_webkdc. It supports
the following individual commands:
- add valid-after
- Adds a new key to the key ring. valid-after uses the format:
nnnn[s|m|h|d|w]
to indicate a time relative to the current time. The units for the time are
specified by appending a single letter. That letter can be any of s, m, h,
d, or w, which correspond to seconds, minutes, hours, days, and weeks
respectively.
For example: 10d is 10 days from the current time, and -60d is 60 days
before the current time.
- gc oldest-valid-after-to-keep
- Garbage collects (removes) old keys on the key ring. Any keys with a
valid-after date older then the specified time will be removed from
the key ring.
The format for oldest-valid-after-to-keep is the same as
valid-after from the add command. Note that this means that times
given to the gc command should generally be negative, to remove keys that
have expired in the past.
- list
- Lists all the keys in the key ring. By default, a brief listing is used,
but a verbose listing can be requested with the -v option.
The following fields are present in a short listing:
- id
- The index/position of the key in the key ring.
- Created
- The date the key was created.
- Valid after
- The date at which the key becomes valid (in other words, the point at
which the WebAuth server will start using it to encrypt and decrypt new
data).
- Fingerprint
- The MD5 digest of the key data. Used to compare keys in two key
rings.
The following fields are present in the long listing:
- Key-Id
- The index/position of the key in the key ring.
- Created
- The date the key was created.
- Valid-After
- The date at which the key becomes valid (in other words, the point at
which the WebAuth server will start using it to encrypt and decrypt new
data).
- Key-Type
- The type of key. Currently, AES is the only supported key type.
- Key-Size
- Length in bytes of the key.
- Fingerprint
- The MD5 digest of the key data. Used to compare keys in two key
rings.
- remove id
- Remove the key with ID id from the key ring.
For any of the commands that change the keyring,
wa_keyring must have
write access to the directory containing the keyring, since keyrings are
updated by writing out the new file to a separate name and then atomically
replacing the file.
Ownership (user and group) of the existing keyring file will be preserved if
possible without overwriting the existing file. Permissions will also be
preserved, with the exception that permissions will not be copied to the new
file if the old file was group-readable or group-writable and setting the
group ownership failed.
EXAMPLES¶
Add a key to the keyring valid as of the current time:
wa_keyring -f keyring add 0d
Add a key to the keyring that will be valid three days from now:
wa_keyring -f keyring add 3d
Remove keys from the key ring that became invalid more than 90 days ago:
wa_keyring -f keyring gc -90d
Remove the first key in the keyring.
wa_keyring -f keyring remove 0
Display a verbose listing of all of the keys in the key ring:
wa_keyring -f keyring -v list
Note that a WebAuth server will normally manage its keyring file by itself, and
wa_keyring is normally only used for debugging purposes. However, if
you are setting up a load-balanced pool of servers that need to all share the
same keys, turn off automatic keyring handling by putting the line:
WebAuthKeyringAutoUpdate off
to your Apache configuration, running a script periodically from cron on one
server that does something like:
wa_keyring -f keyring gc -90d
wa_keyring -f keyring add 2d
and then copying (in a secure manner!) the new keyring file to all of the other
servers.
AUTHOR¶
Roland Schemers <schemers@stanford.edu>
COPYRIGHT AND LICENSE¶
Copyright 2002, 2004, 2005, 2014 The Board of Trustees of the Leland Stanford
Junior University
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved. This file is offered as-is, without any warranty.