path: root/client/wallet.1

.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WALLET 1"
.TH WALLET 1 "2018-06-04" "1.4" "wallet"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
wallet \- Client for retrieving secure data from a central server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBwallet\fR [\fB\-hv\fR] [\fB\-c\fR \fIcommand\fR] [\fB\-f\fR \fIfile\fR]
    [\fB\-k\fR \fIprincipal\fR] [\fB\-p\fR \fIport\fR] [\fB\-s\fR\ \fIserver\fR]
    [\fB\-S\fR \fIsrvtab\fR] [\fB\-u\fR \fIprincipal\fR] \fIcommand\fR [\fIarg\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBwallet\fR 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.
.PP
The \fBwallet\fR 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.
.PP
The primary commands of the wallet system are \f(CW\*(C`get\*(C'\fR, which retrieves some
secure data from the wallet, \f(CW\*(C`store\*(C'\fR, which stores some secure data in
the wallet, and \f(CW\*(C`show\*(C'\fR, 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 \f(CW\*(C`host/example.com\*(C'\fR Kerberos keytab would have a type of
\&\f(CW\*(C`keytab\*(C'\fR and a name of \f(CW\*(C`host/example.com\*(C'\fR.  The meaning of the name is
specific to each type of object.
.PP
Most other wallet commands besides those three are only available to
wallet administrators.  The exception is attribute commands; see
\&\s-1ATTRIBUTES\s0.  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 \s-1ACL\s0 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 \f(CW\*(C`krb5\*(C'\fR scheme, the identifier is a principal name
and only that principal is authorized by that \s-1ACL\s0 entry.
.PP
To run the wallet command-line client, you must either already have a
Kerberos ticket or use the \fB\-u\fR option.  You can obtain a Kerberos ticket
with \fBkinit\fR and see your current Kerberos tickets with \fBklist\fR.  The
wallet client uses the remctl protocol to talk to the wallet server.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-c\fR \fIcommand\fR" 4
.IX Item "-c command"
The command prefix (remctl type) to use.  Normally this is an internal
implementation detail and the default (\f(CW\*(C`wallet\*(C'\fR) 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.  This option can also be set in
\&\fIkrb5.conf\fR; see \s-1CONFIGURATION\s0 below.
.IP "\fB\-f\fR \fIfile\fR" 4
.IX Item "-f file"
This flag is only used in combination with the \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`store\*(C'\fR
commands.  For \f(CW\*(C`get\*(C'\fR, rather than sending the secure data to standard
output (the default), the secure data will be stored in \fIfile\fR.  For
\&\f(CW\*(C`store\*(C'\fR, the data to be stored will be read from \fIfile\fR.
.Sp
With \f(CW\*(C`get\*(C'\fR, if the object being retrieved is not a keytab object, any
current file named \fIoutput\fR is renamed to \fI\fIoutout\fI.bak\fR before the new
file is created.  \fI\fIoutout\fI.new\fR is used as a temporary file and any
existing file with that name will be deleted.
.Sp
If the object being retrieved is a keytab object and the file \fIoutput\fR
already exists, the downloaded keys will be added to the existing keytab
file \fIoutput\fR.  Old keys are not removed; you may wish to run \f(CW\*(C`kadmin
ktremove\*(C'\fR or an equivalent later to clean up old keys.  \fI\fIoutput\fI.new\fR
is still used as a temporary file and any existing file with that name
will be deleted.
.IP "\fB\-k\fR \fIprincipal\fR" 4
.IX Item "-k principal"
The service principal of the wallet server.  The default is to use the
\&\f(CW\*(C`host\*(C'\fR principal for the wallet server.  The principal chosen must match
one of the keys in the keytab used by \fBremctld\fR on the wallet server.
This option can also be set in \fIkrb5.conf\fR; see \s-1CONFIGURATION\s0 below.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Display a brief summary of options and exit.  All other valid options and
commands are ignored.
.IP "\fB\-p\fR \fIport\fR" 4
.IX Item "-p port"
The port to connect to on the wallet server.  The default is the default
remctl port.  This option can also be set in \fIkrb5.conf\fR; see
\&\s-1CONFIGURATION\s0 below.
.IP "\fB\-S\fR \fIsrvtab\fR" 4
.IX Item "-S srvtab"
This flag is only used in combination with the \f(CW\*(C`get\*(C'\fR command on a
\&\f(CW\*(C`keytab\*(C'\fR object, and must be used in conjunction with the \fB\-f\fR flag.
After the keytab is saved to the file specified by \fB\-f\fR, the \s-1DES\s0 key for
that principal will be extracted and written as a Kerberos v4 srvtab to
the file \fIsrvtab\fR.  Any existing contents of \fIsrvtab\fR will be
destroyed.
.Sp
The Kerberos v4 principal name will be generated from the Kerberos v5
principal name using the \fIkrb5_524_conv_principal()\fR function of the
Kerberos libraries.  See its documentation for more information, but
briefly (and in the absence of special configuration), the Kerberos v4
principal name will be the same as the Kerberos v5 principal name except
that the components are separated by \f(CW\*(C`.\*(C'\fR instead of \f(CW\*(C`/\*(C'\fR; the second
component is truncated after the first \f(CW\*(C`.\*(C'\fR if the first component is one
of the recognized host-based principals (generally \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`imap\*(C'\fR,
\&\f(CW\*(C`pop\*(C'\fR, or \f(CW\*(C`smtp\*(C'\fR); and the first component is \f(CW\*(C`rcmd\*(C'\fR if the Kerberos v5
principal component is \f(CW\*(C`host\*(C'\fR.  The principal name must not contain more
than two components.
.IP "\fB\-s\fR \fIserver\fR" 4
.IX Item "-s server"
The wallet server to connect to.  The default may be set when compiling
the wallet client.  If it isn't, either \fB\-s\fR must be given or the server
must be set in \fIkrb5.conf\fR.  See \s-1CONFIGURATION\s0 below.
.IP "\fB\-u\fR \fIprincipal\fR" 4
.IX Item "-u principal"
Rather than using the user's existing ticket cache for authentication,
authenticate as \fIprincipal\fR first and use those credentials for
authentication to the wallet server.  \fBwallet\fR will prompt for the
password for \fIprincipal\fR.  Non-password authentication methods such as
\&\s-1PKINIT\s0 aren't supported; to use those, run \fBkinit\fR first and use an
existing ticket cache.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Display the version of the \fBwallet\fR client and exit.  All other valid
options and commands are ignored.
.SH "COMMANDS"
.IX Header "COMMANDS"
As mentioned above, most commands are only available to wallet
administrators.  The exceptions are \f(CW\*(C`acl check\*(C'\fR, \f(CW\*(C`check\*(C'\fR, \f(CW\*(C`get\*(C'\fR,
\&\f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`destroy\*(C'\fR, \f(CW\*(C`flag clear\*(C'\fR, \f(CW\*(C`flag set\*(C'\fR, \f(CW\*(C`getattr\*(C'\fR,
\&\f(CW\*(C`setattr\*(C'\fR, and \f(CW\*(C`history\*(C'\fR.  \f(CW\*(C`acl check\*(C'\fR and \f(CW\*(C`check\*(C'\fR can be run by
anyone.  All of the rest of those commands have their own ACLs except
\&\f(CW\*(C`getattr\*(C'\fR and \f(CW\*(C`history\*(C'\fR, which use the \f(CW\*(C`show\*(C'\fR \s-1ACL,\s0 \f(CW\*(C`setattr\*(C'\fR, which
uses the \f(CW\*(C`store\*(C'\fR \s-1ACL,\s0 and \f(CW\*(C`comment\*(C'\fR, which uses the owner or \f(CW\*(C`show\*(C'\fR \s-1ACL\s0
depending on whether one is setting or retrieving the comment.  If the
appropriate \s-1ACL\s0 is set, it alone is checked to see if the user has access.
Otherwise, \f(CW\*(C`destroy\*(C'\fR, \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`getattr\*(C'\fR, \f(CW\*(C`setattr\*(C'\fR,
\&\f(CW\*(C`history\*(C'\fR, and \f(CW\*(C`comment\*(C'\fR access is permitted if the user is authorized
by the owner \s-1ACL\s0 of the object.
.PP
Administrators can run any command on any object or \s-1ACL\s0 except for \f(CW\*(C`get\*(C'\fR
and \f(CW\*(C`store\*(C'\fR.  For \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`store\*(C'\fR, they must still be authorized by
either the appropriate specific \s-1ACL\s0 or the owner \s-1ACL.\s0
.PP
If the locked flag is set on an object, no commands can be run on that
object that change data except the \f(CW\*(C`flags\*(C'\fR commands, nor can the \f(CW\*(C`get\*(C'\fR
command be used on that object.  \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`history\*(C'\fR, \f(CW\*(C`getacl\*(C'\fR,
\&\f(CW\*(C`getattr\*(C'\fR, and \f(CW\*(C`owner\*(C'\fR, \f(CW\*(C`expires\*(C'\fR, or \f(CW\*(C`comment\*(C'\fR without an argument
can still be used on that object.
.PP
For more information on attributes, see \s-1ATTRIBUTES\s0.
.IP "acl add <id> <scheme> <identifier>" 4
.IX Item "acl add <id> <scheme> <identifier>"
Add an entry with <scheme> and <identifier> to the \s-1ACL\s0 <id>.  <id> may be
either the name of an \s-1ACL\s0 or its numeric identifier.
.IP "acl check <id>" 4
.IX Item "acl check <id>"
Check whether an \s-1ACL\s0 with the \s-1ID\s0 <id> already exists.  If it does, prints
\&\f(CW\*(C`yes\*(C'\fR; if not, prints \f(CW\*(C`no\*(C'\fR.
.IP "acl create <name>" 4
.IX Item "acl create <name>"
Create a new, empty \s-1ACL\s0 with name <name>.  When setting an \s-1ACL\s0 on an
object with a set of entries that don't match an existing \s-1ACL,\s0 first
create a new \s-1ACL\s0 with \f(CW\*(C`acl create\*(C'\fR, add the appropriate entries to it
with \f(CW\*(C`acl add\*(C'\fR, and then set the \s-1ACL\s0 on an object with the \f(CW\*(C`owner\*(C'\fR or
\&\f(CW\*(C`setacl\*(C'\fR commands.
.IP "acl destroy <id>" 4
.IX Item "acl destroy <id>"
Destroy the \s-1ACL\s0 <id>.  This \s-1ACL\s0 must no longer be referenced by any object
or the \s-1ACL\s0 destruction will fail.  The special \s-1ACL\s0 named \f(CW\*(C`ADMIN\*(C'\fR cannot
be destroyed.
.IP "acl history <id>" 4
.IX Item "acl history <id>"
Display the history of the \s-1ACL\s0 <id>.  Each change to the \s-1ACL\s0 (not
including changes to the name of the \s-1ACL\s0) will be represented by two
lines.  The first line will have a timestamp of the change followed by a
description of the change, and the second line will give the user who made
the change and the host from which the change was made.
.IP "acl remove <id> <scheme> <identifier>" 4
.IX Item "acl remove <id> <scheme> <identifier>"
Remove the entry with <scheme> and <identifier> from the \s-1ACL\s0 <id>.  <id>
may be either the name of an \s-1ACL\s0 or its numeric identifier.  The last
entry in the special \s-1ACL\s0 \f(CW\*(C`ADMIN\*(C'\fR cannot be removed to protect against
accidental lockout, but administrators can remove themselves from the
\&\f(CW\*(C`ADMIN\*(C'\fR \s-1ACL\s0 and can leave only a non-functioning entry on the \s-1ACL.\s0  Use
caution when removing entries from the \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL.\s0
.IP "acl rename <id> <name>" 4
.IX Item "acl rename <id> <name>"
Renames the \s-1ACL\s0 identified by <id> to <name>.  This changes the
human-readable name, not the underlying numeric \s-1ID,\s0 so the \s-1ACL\s0's
associations with objects will be unchanged.  The \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL\s0 may not be
renamed.  <id> may be either the current name or the numeric \s-1ID.\s0  <name>
must not be all-numeric.  To rename an \s-1ACL,\s0 the current user must be
authorized by the \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL.\s0
.IP "acl replace <id> <new\-id>" 4
.IX Item "acl replace <id> <new-id>"
Find any objects owned by <id>, and then change their ownership to
<new_id> instead.  <new\-id> should already exist, and may already have
some objects owned by it.  <id> is not deleted afterwards, though in
most cases that is probably your next step.  The \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL\s0 may not be
replaced from.  <id> and <new\-id> may be either the current name or the
numeric \s-1ID.\s0  To replace an \s-1ACL,\s0 the current user must be authorized by
the \f(CW\*(C`ADMIN\*(C'\fR \s-1ACL.\s0
.IP "acl show <id>" 4
.IX Item "acl show <id>"
Display the name, numeric \s-1ID,\s0 and entries of the \s-1ACL\s0 <id>.
.IP "autocreate <type> <name>" 4
.IX Item "autocreate <type> <name>"
Create a new object of type <type> with name <name>.  The user must be
listed in the default \s-1ACL\s0 for an object with that type and name, and the
object will be created with that default \s-1ACL\s0 set as the object owner.
.Sp
Normally, there's no need to run this command directly.  It's
automatically run when trying to get or store an object that doesn't
already exist.
.IP "check <type> <name>" 4
.IX Item "check <type> <name>"
Check whether an object of type <type> and name <name> already exists.  If
it does, prints \f(CW\*(C`yes\*(C'\fR; if not, prints \f(CW\*(C`no\*(C'\fR.
.IP "comment <type> <name> [<comment>]" 4
.IX Item "comment <type> <name> [<comment>]"
If <comment> is not given, displays the current comment for the object
identified by <type> and <name>, or \f(CW\*(C`No comment set\*(C'\fR if none is set.
.Sp
If <comment> is given, sets the comment on the object identified by
<type> and <name> to <comment>.  If <comment> is the empty string, clears
the comment.
.IP "create <type> <name>" 4
.IX 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 \f(CW\*(C`owner\*(C'\fR so that the
object will be usable.
.IP "destroy <type> <name>" 4
.IX 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.
.IP "expires <type> <name> [<expires>]" 4
.IX Item "expires <type> <name> [<expires>]"
If <expires> is not given, displays the current expiration of the object
identified by <type> and <name>, or \f(CW\*(C`No expiration set\*(C'\fR if none is set.
The expiration will be displayed in seconds since epoch.
.Sp
If <expires> is given, sets the expiration on the object identified by
<type> and <name> to that date (and optionally time).  <expires> must be
in some format that can be parsed by the Perl Date::Parse module.  Most
common formats are supported; if in doubt, use \f(CW\*(C`YYYY\-MM\-DD HH:MM:SS\*(C'\fR.  If
<expires> is the empty string, clears the expiration of the object.
.Sp
Currently, the expiration of an object is not used.
.IP "flag clear <type> <name> <flag>" 4
.IX Item "flag clear <type> <name> <flag>"
Clears the flag <flag> on the object identified by <type> and <name>.
.IP "flag set <type> <name> <flag>" 4
.IX Item "flag set <type> <name> <flag>"
Sets the flag <flag> on the object identified by <type> and <name>.
Recognized flags are \f(CW\*(C`locked\*(C'\fR, which prevents all further actions on that
object until the flag is cleared, and \f(CW\*(C`unchanging\*(C'\fR, which tells the object
backend to not generate new data on get but instead return the same data as
previously returned.  The \f(CW\*(C`unchanging\*(C'\fR flag is not meaningful for objects
that do not generate new data on the fly.
.IP "get <type> <name>" 4
.IX Item "get <type> <name>"
Prints to standard output the data associated with the object identified
by <type> and <name>, or stores it in a file if the \fB\-f\fR option was
given.  This may trigger generation of new data and invalidate old data
for that object depending on the object type.
.Sp
If an object with type <type> and name <name> does not already exist when
this command is issued (as checked with the check interface), \fBwallet\fR
will attempt to automatically create it (using autocreate).
.IP "getacl <type> <name> <acl>" 4
.IX Item "getacl <type> <name> <acl>"
Prints the \s-1ACL\s0 <acl>, which must be one of \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR,
\&\f(CW\*(C`destroy\*(C'\fR, or \f(CW\*(C`flags\*(C'\fR, for the object identified by <type> and <name>.
Prints \f(CW\*(C`No ACL set\*(C'\fR if that \s-1ACL\s0 isn't set on that object.  Remember that
if the \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, or \f(CW\*(C`show\*(C'\fR ACLs aren't set, authorization falls
back to checking the owner \s-1ACL.\s0  See the \f(CW\*(C`owner\*(C'\fR command for displaying
or setting it.
.IP "getattr <type> <name> <attr>" 4
.IX Item "getattr <type> <name> <attr>"
Prints the object attribute <attr> for the object identified by <type> and
<name>.  Attributes are used to store backend-specific information for a
particular object type, and <attr> must be an attribute type known to the
underlying object implementation.  The attribute values, if any, are
printed one per line.  If the attribute is not set on this object, nothing
is printed.
.IP "history <type> <name>" 4
.IX Item "history <type> <name>"
Displays the history for the object identified by <type> and <name>.
This human-readable output will have two lines for each action that
changes the object, plus for any get action.  The first line has the
timestamp of the action and the action, and the second line gives the user
who performed the action and the host from which they performed it.
.IP "owner <type> <name> [<owner>]" 4
.IX Item "owner <type> <name> [<owner>]"
If <owner> is not given, displays the current owner \s-1ACL\s0 of the object
identified by <type> and <name>, or \f(CW\*(C`No owner set\*(C'\fR if none is set.  The
result will be the name of an \s-1ACL.\s0
.Sp
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.
.IP "setacl <type> <name> <acl> <id>" 4
.IX Item "setacl <type> <name> <acl> <id>"
Sets the \s-1ACL\s0 <acl>, which must be one of \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`store\*(C'\fR, \f(CW\*(C`show\*(C'\fR,
\&\f(CW\*(C`destroy\*(C'\fR, or \f(CW\*(C`flags\*(C'\fR, to <id> on the object identified by <type> and
<name>.  If <id> is the empty string, clears that \s-1ACL\s0 on the object.
.IP "setattr <type> <name> <attr> <value> [<value> ...]" 4
.IX Item "setattr <type> <name> <attr> <value> [<value> ...]"
Sets the object attribute <attr> for the object identified by <type> and
<name>.  Attributes are used to store backend-specific information for a
particular object type, and <attr> must be an attribute type known to the
underlying object implementation.  To clear the attribute for this object,
pass in a <value> of the empty string (\f(CW\*(Aq\*(Aq\fR).
.IP "show <type> <name>" 4
.IX 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.
.IP "store <type> <name> [<data>]" 4
.IX Item "store <type> <name> [<data>]"
Stores <data> for the object identified by <type> and <name> for later
retrieval with \f(CW\*(C`get\*(C'\fR.  Not all object types support this.  If <data> is
not specified on the command line, it will be read from the file specified
with \fB\-f\fR (if given) or from standard input.
.Sp
If an object with type <type> and name <name> does not already exist when
this command is issued (as checked with the check interface), \fBwallet\fR
will attempt to automatically create it (using autocreate).
.IP "update <type> <name>" 4
.IX Item "update <type> <name>"
Prints to standard output the data associated with the object identified
by <type> and <name>, or stores it in a file if the \fB\-f\fR option was
given.  This will generate new data in the object, and only works for 
objects that support generating new data automatically, such as keytabs or
passwords.  Types that do not support generating new data will fail and
direct you to use get instead.
.Sp
If an object with type <type> and name <name> does not already exist when
this command is issued (as checked with the check interface), \fBwallet\fR
will attempt to automatically create it (using autocreate).
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Object attributes store additional properties and configuration
information for objects stored in the wallet.  They are displayed as part
of the object data with \f(CW\*(C`show\*(C'\fR, retrieved with \f(CW\*(C`getattr\*(C'\fR, and set with
\&\f(CW\*(C`setattr\*(C'\fR.
.SS "Keytab Attributes"
.IX Subsection "Keytab Attributes"
Keytab objects support the following attributes:
.IP "enctypes" 4
.IX Item "enctypes"
Restricts the generated keytab to a specific set of encryption types.  The
values of this attribute must be enctype strings recognized by Kerberos
(strings like \f(CW\*(C`aes256\-cts\-hmac\-sha1\-96\*(C'\fR or \f(CW\*(C`des\-cbc\-crc\*(C'\fR).  Note that
the salt should not be included; since the salt is irrelevant for keytab
keys, it will always be set to \f(CW\*(C`normal\*(C'\fR by the wallet.
.Sp
If this attribute is set, the specified enctype list will be passed to ktadd
when \fIget()\fR is called for that keytab.  If it is not set, the default set in
the \s-1KDC\s0 will be used.
.Sp
This attribute is ignored if the \f(CW\*(C`unchanging\*(C'\fR flag is set on a keytab.
Keytabs retrieved with \f(CW\*(C`unchanging\*(C'\fR set will contain all keys present in
the \s-1KDC\s0 for that Kerberos principal and therefore may contain different
enctypes than those requested by this attribute.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
\&\fBwallet\fR can optionally be configured in the system \fIkrb5.conf\fR.  It
will read the default \fIkrb5.conf\fR file for the Kerberos libraries with
which it was compiled.  To set an option, put the option in the
[appdefaults] section.  \fBwallet\fR will look for options either at the top
level of the [appdefaults] section or in a subsection named \f(CW\*(C`wallet\*(C'\fR.
For example, the following fragment of a \fIkrb5.conf\fR file would set the
default port to 4373 and the default server to \f(CW\*(C`wallet.example.org\*(C'\fR.
.PP
.Vb 5
\&    [appdefaults]
\&        wallet_port = 4373
\&        wallet = {
\&            wallet_server = wallet.example.org
\&        }
.Ve
.PP
The supported options are:
.IP "wallet_principal" 4
.IX Item "wallet_principal"
The service principal of the wallet server.  The default is to use the
\&\f(CW\*(C`host\*(C'\fR principal for the wallet server.  The principal chosen must match
one of the keys in the keytab used by \fBremctld\fR on the wallet server.
The \fB\-k\fR command-line option overrides this setting.
.IP "wallet_port" 4
.IX Item "wallet_port"
The port to connect to on the wallet server.  The default is the default
remctl port.  The \fB\-p\fR command-line option overrides this setting.
.IP "wallet_server" 4
.IX Item "wallet_server"
The wallet server to connect to.  The \fB\-s\fR command-line option overrides
this setting.  The default may be set when compiling the wallet client.
If it isn't, either \fB\-s\fR must be given or this parameter must be present
in in \fIkrb5.conf\fR.
.IP "wallet_type" 4
.IX Item "wallet_type"
The command prefix (remctl type) to use.  Normally this is an internal
implementation detail and the default (\f(CW\*(C`wallet\*(C'\fR) 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.  The \fB\-c\fR command-line option
overrides this setting.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery <eagle@eyrie.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2007\-2008, 2010\-2013 The Board of Trustees of the Leland
Stanford Junior University
.PP
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved.  This file is offered as-is, without any
warranty.
.PP
SPDX-License-Identifier: \s-1FSFAP\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIkadmin\fR\|(8), \fIkinit\fR\|(1), \fIkrb5.conf\fR\|(5), \fIremctl\fR\|(1), \fIremctld\fR\|(8)
.PP
This program is part of the wallet system.  The current version is available
from <https://www.eyrie.org/~eagle/software/wallet/>.
.PP
\&\fBwallet\fR uses the remctl protocol.  For more information about remctl,
see <https://www.eyrie.org/~eagle/software/remctl/>.