NAME

       WebAuth::Keyring - WebAuth keyring to hold encryption and decryption keys

SYNOPSIS

           use WebAuth qw(WA_KEY_AES WA_AES_128);
           use WebAuth::Key;
           use WebAuth::Keyring;

           my $wa = WebAuth->new;
           eval {
               $key = WebAuth::Key->new ($wa, WA_KEY_AES, WA_AES_128);
               $ring = WebAuth::Keyring->new ($wa, $key);
               ...
           };
           if ($@) {
               # handle exception
           }

DESCRIPTION

       This Perl class represents a keyring, which is a set of WebAuth keys with associated
       creation times and times after which they become valid.  These keyrings can be read from
       and stored to files on disk and are used by WebAuth Application Servers and WebKDCs to
       store their encryption keys.

       A WebAuth::Keyring object will be destroyed when the WebAuth context used to create it is
       destroyed, and subsequent accesses to it may cause memory access errors or other serious
       bugs.  Be careful not to retain a copy of a WebAuth::Keyring object after the WebAuth
       object that created it has been destroyed.

CLASS METHODS

       As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception
       rather than by return status.

       new (WEBAUTH, KEY)
       new (WEBAUTH, SIZE)
           Create a new keyring attached to the WebAuth context WEBAUTH.

           The second argument to this method may be either a WebAuth::Key object or a numeric
           size.  If a WebAuth::Key object is provided, a new keyring containing only that key
           will be created and returned.  If a size is provided, a new, empty keyring with space
           preallocated to hold that many keys is created and returned.  (Regardless of the
           allocated size of a keyring, keyrings will always dynamically expand to hold any new
           keys that are added to them.)

           This is a convenience wrapper around the WebAuth keyring_new() method.

       decode (WEBAUTH, FILE)
           Create a new WebAuth::Keyring object by decoding its contents from the provided
           serialized keyring data.

           This is a convenience wrapper around the WebAuth keyring_read() method.

       read (WEBAUTH, FILE)
           Create a new WebAuth::Keyring object by reading its contents from the provided file.
           The created keyring object will have no association with the file after being created;
           it won't automatically be saved, or updated when the file changes.

           This is a convenience wrapper around the WebAuth keyring_read() method.

INSTANCE METHODS

       As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception
       rather than by return status.

       add (CREATION, VALID_AFTER, KEY)
           Add a new KEY to the keyring with CREATION as the creation time and VALID_AFTER as the
           valid-after time.  Both of the times should be in seconds since epoch.  The key must
           be a WebAuth::Key object.

           Keys will not used for encryption until after their valid-after time, which provides
           an opportunity to synchronize the keyring between multiple systems before the keys are
           used.

       best_key (USAGE, HINT)
           Returns the best key available in the keyring for a particular purpose and time.
           USAGE should be either WebAuth::WA_KEY_DECRYPT or WebAuth::WA_KEY_ENCRYPT and
           indicates whether the key will be used for decryption or encryption.  For decryption
           keys, HINT is the timestamp of the data that will be decrypted.

           If USAGE is WebAuth::WA_KEY_ENCRYPT, this method will return the valid key in the
           keyring that was created most recently, since this is the best key to use for
           encryption going forward.  If USAGE is WebAuth::WA_KEY_DECRYPT is false, this method
           will return the key most likely to have been used to encrypt something at the time
           HINT, where HINT is given in seconds since epoch.

       encode ()
           Encode the keyring in the same serialization format that is used when writing it to a
           file, readable by decode() or read(), and return the encoded form.

       entries ()
           In a scalar context, returns the number of entries in the keyring.  In an array
           context, returns a list of keyring entries as WebAuth::KeyringEntry objects.

       remove (INDEX)
           Removes the INDEX entry in the keyring, where INDEX is a numeric key number starting
           from 0.  The keyring will then be compacted, so all subsequent entries in the keyring
           will have their index decreased by one.  If you are removing multiple entries from a
           keyring, you should therefore remove them from the end of the keyring (the highest
           INDEX number) first.

       write (FILE)
           Writes the keyring out to FILE in the format suitable for later reading by read().

AUTHOR

       Russ Allbery <rra@stanford.edu>

SEE ALSO

       WebAuth(3), WebAuth::Key(3), WebAuth::KeyringEntry(3)

       This module is part of WebAuth.  The current version is available from
       <http://webauth.stanford.edu/>.