diff options
| -rw-r--r-- | client/wallet.pod | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/client/wallet.pod b/client/wallet.pod new file mode 100644 index 0000000..8ae4e58 --- /dev/null +++ b/client/wallet.pod @@ -0,0 +1,236 @@ +=head1 NAME + +wallet - Client for retrieving secure data from a central server + +=head1 SYNOPSIS + +B<wallet> [B<-hv>] [B<-c> I<command>] [B<-f> I<output>] +[B<-k> I<principal>] [B<-p> I<port>] [B<-s> I<server>] I<command> +[I<arg> ...] + +=head1 DESCRIPTION + +B<wallet> is a client for the wallet system, which stores or creates +secure information such as Kerberos keytabs, associates them with ACLs and +other metadata, and allows clients to view and download them. This client +provides the user interface to the wallet system for both users and wallet +administrators. + +The B<wallet> command-line client takes a command and optional arguments +on the command line, authenticates to the wallet server using Kerberos, +and sends that command and arguments to server. It then reads the results +and displays them to the user or stores them in a file. The client itself +does not know which commands are valid and which aren't; apart from some +special handling of particular commands, it sends all commands to the +server to respond to appropriately. This allows additional commands to be +added to the wallet system without changing all of the clients. + +The primary commands of the wallet system are C<get>, which retrieves some +secure data from the wallet, C<store>, which stores some secure data in +the wallet, and C<show>, which stores the metadata about an object stored +in the wallet. Each object in the wallet has a type, which determines +what data the object represents and may determine special handling when +downloading or storing that object, and a name. For example, a wallet +object for the C<host/example.com> Kerberos keytab would have a type of +C<keytab> and a name of C<host/example.com>. The meaning of the name is +specific to each type of object. + +Most other wallet commands besides those three are only available to +wallet administrators. The other commands allow setting ownership and +ACLs on objects, creating and destroying objects, creating and destroying +ACLs, and adding and removing entries from ACLs. An ACL consists of one +or more entries, each of which is a scheme and an identifier. A scheme +specifies a way of checking whether a user is authorized. An identifier +is some data specific to the scheme that specifies which users are +authorized. For example, for the C<krb5> scheme, the identifier is a +principal name and only that principal is authorized by that ACL entry. +For the C<pts> scheme, the identifier is a PTS group name, and all members +of that PTS group are authorized by that ACL entry. + +To run the wallet command-line client, you must already have a Kerberos +ticket. You can obtain a Kerberos ticket with B<kinit> and see your +current Kerberos tickets with B<klist>. The wallet client uses the remctl +protocol to talk to the wallet server. + +=head1 OPTIONS + +=over 4 + +=item B<-c> I<command> + +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (C<wallet>) should be fine. It may +sometimes be useful to use a different prefix for testing a different +version of the wallet code on the server. + +=item B<-f> I<output> + +This flag is only used in combination with the C<get> command. Rather +than sending the secure data to standard output (the default), store the +secure data in the file I<output>. Any existing contents of I<output> +will be destroyed. + +=item B<-k> I<principal> + +The service principal of the wallet server. The default is to use the +C<host> principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by B<remctld> on the wallet server. + +=item B<-h> + +Display a brief summary of options and exit. All other valid options and +commands are ignored. + +=item B<-p> I<port> + +The port to connect to on the wallet server. The default is the default +remctl port (4444). + +=item B<-s> I<server> + +The wallet server to connect to. The default is a hard-coded server value +determined at configure time when compiling the wallet client. + +=item B<-v> + +Display the version of the B<wallet> client and exit. All other valid +options and commands are ignored. + +=back + +=head1 COMMANDS + +As mentioned above, most commands are only available to wallet +administrators. The exceptions are C<get>, C<store>, C<show>, and +C<destroy>. All of those commands have their own ACLs, and if the +appropriate ACL is set, it alone is checked to see if the user has access. +Otherwise, C<get>, C<store>, and C<show> access is permitted if the user +is authorized by the owner ACL of the object. + +Administrators can run any command on any object or ACL except for C<get> +and C<store>. For C<get> and C<show>, they must still be authorized by +either the appropriate specific ACL or the owner ACL. + +=over 4 + +=item acl add <id> <scheme> <identifier> + +Adds an entry with <scheme> and <identifier> to the ACL <id>. <id> may be +either the name of an ACL or its numeric identifier. + +=item acl create <name> + +Create a new, empty ACL with name <name>. When setting an ACL on an +object with a set of entries that don't match an existing ACL, first +create a new ACL with C<acl create>, add the appropriate entries to it +with C<acl add>, and then set the ACL on an object with the C<owner> or +C<setacl> commands. + +=item acl destroy <id> + +Destroy the ACL <id>. This ACL must no longer be referenced by any object +or the ACL destruction will fail. The special ACL named C<ADMIN> cannot +be destroyed. + +=item acl remove <id> <scheme> <identifier> + +Remove the entry with <scheme> and <identifier> from the ACL <id>. <id> +may be either the name of an ACL or its numeric identifier. The last +entry in the special ACL C<ADMIN> cannot be removed to protect against +accidental lockout, but administrators can remove themselves from the +C<ADMIN> ACL and can leave only a non-functioning entry on the ACL. Use +caution when removing entries from the C<ADMIN> ACL. + +=item create <type> <name> + +Create a new object of type <type> with name <name>. With some backends, +this will trigger creation of an entry in an external system as well. +The new object will have no ACLs and no owner set, so usually the +administrator will want to then set an owner with C<owner> so that the +object will be usable. + +=item destroy <type> <name> + +Destroy the object identified by <type> and <name>. With some backends, +this will trigger destruction of an object in an external system as well. + +=item expires <type> <name> [<expires>] + +If <expires> is not given, displays the current expiration of the object +identified by <type> and <name>, or C<No expiration set> if none is set. +The expiration will be displayed in seconds since epoch. + +If <expires> is given, sets the expiration on the object identified by +<type> and <name> to <expires>. <expires> should be given in seconds +since epoch. If <expires> is the empty string, clears the expiration of +the object. + +Currently, the expiration of an object is not used. + +=item get <type> <output> + +Prints to standard output the data associated with the object identified +by <type> and <name>, or stores it in a file if the B<-f> option was +given. This may trigger generation of new data and invalidate old data +for that object depending on the object type. + +=item getacl <type> <name> <acl> + +Prints the ACL <acl>, which must be one of C<get>, C<store>, C<show>, +C<destroy>, or C<flags>, for the object identified by <type> and <name>. +Prints C<No ACL set> if that ACL isn't set on that object. Remember that +if the C<get>, C<store>, or C<show> ACLs aren't set, authorization falls +back to checking the owner ACL. See the C<owner> command for displaying +or setting it. + +=item owner <type> <name> [<owner>] + +If <owner> is not given, displays the current owner ACL of the object +identified by <type> and <name>, or C<No owner set> if none is set. The +result will be the name of an ACL. + +If <owner> is given, sets the owner of the object identified by <type> and +<name> to <owner>. If <owner> is the empty string, clears the owner of +the object. + +=item setacl <type> <name> <acl> <id> + +Sets the ACL <acl>, which must be one of C<get>, C<store>, C<show>, +C<destroy>, or C<flags>, to <id> on the object identified by <type> and +<name>. If <id> is the empty string, clears that ACL on the object. + +=item show <type> <name> + +Displays the current object metadata for the object identified by <type> +and <name>. This human-readable output will show the object type and +name, the owner, any specific ACLs set on the object, the expiration if +any, and the user, remote host, and time when the object was created, last +stored, and last downloaded. + +=item store <type> <name> <data> + +Stores <data> for the object identified by <type> and <name> for later +retrieval with C<get>. Not all object types support this. + +Currently, <data> is limited to not containing nul characters and may +therefore not be binary data, and is limited by the maximum command line +length of the operating system of the wallet server. These restrictions +will be lifted in the future. + +=back + +=head1 SEE ALSO + +remctl(1), remctld(8) + +This program is part of the wallet system. The current version is available +from L<http://www.eyrie.org/~eagle/software/wallet/>. + +B<wallet> uses the remctl protocol. For more information about remctl, +see L<http://www.eyrie.org/~eagle/software/remctl/>. + +=head1 AUTHOR + +Russ Allbery <rra@stanford.edu> + +=cut |