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.

4.7.0                                              2014-12-10                                      WA_KEYRING(1)