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 <eagle@eyrie.org>
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/>.