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>