| < Wallet::Object::Password API | Russ Allbery > Software > wallet | Wallet::Policy::Stanford API > |
(WebAuth keyring object implementation for wallet)
my ($user, $host, $time);
my @name = qw(wa-keyring www.stanford.edu);
my @trace = ($user, $host, $time);
my $object = Wallet::Object::WAKeyring->create (@name, $schema, $trace);
my $keyring = $object->get (@trace);
unless ($object->store ($keyring)) {
die $object->error, "\n";
}
$object->destroy (@trace);
Wallet::Object::WAKeyring is a representation of a WebAuth keyring in the wallet. It implements the wallet object API and provides the necessary glue to store a keyring on the wallet server, retrieve it, update the keyring with new keys automatically as needed, purge old keys automatically, and delete the keyring when the object is deleted.
WebAuth keyrings hold one or more keys. Each key has a creation time and a validity time. The key cannot be used until its validity time has been reached. This permits safe key rotation: a new key is added with a validity time in the future, and then the keyring is updated everywhere it needs to be before that validity time is reached. This wallet object automatically handles key rotation by adding keys with validity dates in the future and removing keys with creation dates substantially in the past.
To use this object, various configuration options specifying where to store the keyrings and how to handle key rotation must be set. See Wallet::Config for details on these configuration parameters and information about how to set wallet configuration.
This object mostly inherits from Wallet::Object::Base. See the documentation for that class for all generic methods. Below are only those methods that are overridden or behave specially for this implementation.
Destroys a WebAuth keyring object by removing it from the database and deleting the corresponding file on the wallet server. Returns true on success and false on failure. The caller should call error() to get the error message after a failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used.
Either creates a new WebAuth keyring (if this object has not bee stored or retrieved before) or does any necessary periodic maintenance on the keyring and then returns its data. The caller should call error() to get the error message if get() returns undef. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is downloading the keytab. If DATETIME isn't given, the current time is used.
If this object has never been stored or retrieved before, a new keyring will be created with three 128-bit AES keys: one that is immediately valid, one that will become valid after the rekey interval, and one that will become valid after twice the rekey interval.
If keyring data for this object already exists, the creation and validity dates for each key in the keyring will be examined. If the key with the validity date the farthest into the future has a date that's less than or equal to the current time plus the rekey interval, a new 128-bit AES key will be added to the keyring with a validity time of twice the rekey interval in the future. Finally, all keys with a creation date older than the configured purge interval will be removed provided that the keyring has at least three keys
Store DATA as the current contents of the WebAuth keyring object. Note that this is not checked for validity, just assumed to be a valid keyring. Any existing data will be overwritten. Returns true on success and false on failure. The caller should call error() to get the error message after a failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used.
If FILE_MAX_SIZE is set in the wallet configuration, a store() of DATA larger than that configuration setting will be rejected.
WebAuth keyrings are stored on the wallet server under the directory WAKEYRING_BUCKET as set in the wallet configuration. <hash> is the first two characters of the hex-encoded MD5 hash of the wallet file object name, used to not put too many files in the same directory. <file> is the name of the file object with all characters other than alphanumerics, underscores, and dashes replaced by "%" and the hex code of the character.
Wallet::Config(3), Wallet::Object::Base(3), wallet-backend(8), WebAuth(3)
This module is part of the wallet system. The current version is available from <https://www.eyrie.org/~eagle/software/wallet/>.
Russ Allbery <eagle@eyrie.org>
| < Wallet::Object::Password API | Russ Allbery > Software > wallet | Wallet::Policy::Stanford API > |