Add Wallet::Object::WAKeyring documentation

Change-Id: I12e430acd089de5ac50f62ebbdeb869be31eeeec
Reviewed-on: https://gerrit.stanford.edu/711
Reviewed-by: Russ Allbery <rra@stanford.edu>
Tested-by: Russ Allbery <rra@stanford.edu>

1 files changed, 120 insertions, 3 deletions

diff --git a/perl/Wallet/Object/WAKeyring.pm b/perl/Wallet/Object/WAKeyring.pm
index e80df18..300bcda 100644
--- a/perl/Wallet/Object/WAKeyring.pm
+++ b/perl/Wallet/Object/WAKeyring.pm
@@ -1,7 +1,7 @@
 # Wallet::Object::WAKeyring -- WebAuth keyring object implementation.
 #
 # Written by Russ Allbery <rra@stanford.edu>
-# Copyright 2012
+# Copyright 2012, 2013
 #     The Board of Trustees of the Leland Stanford Junior University
 #
 # See LICENSE for licensing terms.
@@ -159,6 +159,8 @@ sub get {
     # only do so if we have more than three keys (the one that's currently
     # active, the one that's going to come active in the rekey interval, and
     # the one that's going to come active after that.
+    #
+    # FIXME: Be sure that we don't remove the last currently-valid key.
     my $cutoff = time - $Wallet::Config::WAKEYRING_PURGE_INTERVAL;
     my $i = 0;
     my @purge;
@@ -201,6 +203,8 @@ sub get {
 }
 
 # Store the file on the wallet server.
+#
+# FIXME: Check the provided keyring for validity.
 sub store {
     my ($self, $data, $user, $host, $time) = @_;
     $time ||= time;
@@ -239,14 +243,127 @@ __END__
 ##############################################################################
 
 =for stopwords
-WebAuth keyring
+WebAuth keyring keyrings API HOSTNAME DATETIME keytab AES rekey Allbery
 
 =head1 NAME
 
 Wallet::Object::WAKeyring - WebAuth keyring object implementation for wallet
 
+=head1 SYNOPSIS
+
+    my ($user, $host, $time);
+    my @name = qw(wa-keyring www.stanford.edu);
+    my @trace = ($user, $host, $time);
+    my $object = Wallet::Object::WAKeyring->create (@name, $dbh, $trace);
+    my $keyring = $object->get (@trace);
+    unless ($object->store ($keyring)) {
+        die $object->error, "\n";
+    }
+    $object->destroy (@trace);
+
 =head1 DESCRIPTION
 
-To be written.
+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.
+
+=head1 METHODS
+
+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.
+
+=over 4
+
+=item destroy(PRINCIPAL, HOSTNAME [, DATETIME])
+
+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.
+
+=item get(PRINCIPAL, HOSTNAME [, DATETIME])
+
+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
+
+=item store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
+
+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.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item WAKEYRING_BUCKET/<hash>/<file>
+
+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.
+
+=back
+
+=head1 SEE ALSO
+
+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 <http://www.eyrie.org/~eagle/software/wallet/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
 
 =cut