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