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

perl v5.18.1                                       2013-10-22                              WebAuth::Keyring(3pm)