From 6fce629d4ab59b13c0a7527c6e9aa1561ce20330 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 1 Sep 2007 04:00:16 +0000 Subject: Add documentation for the wallet command-line client. --- client/wallet.pod | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 client/wallet.pod 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 [B<-hv>] [B<-c> I] [B<-f> I] +[B<-k> I] [B<-p> I] [B<-s> I] I +[I ...] + +=head1 DESCRIPTION + +B 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 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, which retrieves some +secure data from the wallet, C, which stores some secure data in +the wallet, and C, 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 Kerberos keytab would have a type of +C and a name of C. 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 scheme, the identifier is a +principal name and only that principal is authorized by that ACL entry. +For the C 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 and see your +current Kerberos tickets with B. The wallet client uses the remctl +protocol to talk to the wallet server. + +=head1 OPTIONS + +=over 4 + +=item B<-c> I + +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (C) 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 + +This flag is only used in combination with the C command. Rather +than sending the secure data to standard output (the default), store the +secure data in the file I. Any existing contents of I +will be destroyed. + +=item B<-k> I + +The service principal of the wallet server. The default is to use the +C principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by B 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 + +The port to connect to on the wallet server. The default is the default +remctl port (4444). + +=item B<-s> I + +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 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, C, C, and +C. 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, C, and C 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 +and C. For C and C, they must still be authorized by +either the appropriate specific ACL or the owner ACL. + +=over 4 + +=item acl add + +Adds an entry with and to the ACL . may be +either the name of an ACL or its numeric identifier. + +=item acl create + +Create a new, empty ACL with 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, add the appropriate entries to it +with C, and then set the ACL on an object with the C or +C commands. + +=item acl destroy + +Destroy the ACL . This ACL must no longer be referenced by any object +or the ACL destruction will fail. The special ACL named C cannot +be destroyed. + +=item acl remove + +Remove the entry with and from the ACL . +may be either the name of an ACL or its numeric identifier. The last +entry in the special ACL C cannot be removed to protect against +accidental lockout, but administrators can remove themselves from the +C ACL and can leave only a non-functioning entry on the ACL. Use +caution when removing entries from the C ACL. + +=item create + +Create a new object of type with 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 so that the +object will be usable. + +=item destroy + +Destroy the object identified by and . With some backends, +this will trigger destruction of an object in an external system as well. + +=item expires [] + +If is not given, displays the current expiration of the object +identified by and , or C if none is set. +The expiration will be displayed in seconds since epoch. + +If is given, sets the expiration on the object identified by + and to . should be given in seconds +since epoch. If is the empty string, clears the expiration of +the object. + +Currently, the expiration of an object is not used. + +=item get + +Prints to standard output the data associated with the object identified +by and , 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 + +Prints the ACL , which must be one of C, C, C, +C, or C, for the object identified by and . +Prints C if that ACL isn't set on that object. Remember that +if the C, C, or C ACLs aren't set, authorization falls +back to checking the owner ACL. See the C command for displaying +or setting it. + +=item owner [] + +If is not given, displays the current owner ACL of the object +identified by and , or C if none is set. The +result will be the name of an ACL. + +If is given, sets the owner of the object identified by and + to . If is the empty string, clears the owner of +the object. + +=item setacl + +Sets the ACL , which must be one of C, C, C, +C, or C, to on the object identified by and +. If is the empty string, clears that ACL on the object. + +=item show + +Displays the current object metadata for the object identified by +and . 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 + +Stores for the object identified by and for later +retrieval with C. Not all object types support this. + +Currently, 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. + +B uses the remctl protocol. For more information about remctl, +see L. + +=head1 AUTHOR + +Russ Allbery + +=cut -- cgit v1.2.3