WALLET(1)

📦 version 1.7, in debian trixie, ubuntu resolute, ubuntu stonking

WALLET(1) 💖

okay bestie, welcome to the wallet manual page — section 1. we are keeping every fact, just with main character energy. no cap. ✨

✨ NAME ✨

wallet — Client for retrieving secure data from a central server

🦋 SYNOPSIS 🦋

wallet [-hv] [-c command] [-f file]
    [-k principal] [-p port] [-s server]
    [-S srvtab] [-u principal] command [arg ...]

🌸 DESCRIPTION 🌸

wallet is the client side of the wallet system. The wallet system stores or creates secure info like Kerberos keytabs, ties them to ACLs and other metadata, and lets clients view and download them. This client is the user interface for both regular users and wallet admins. 🫶

So the wallet command-line client takes a command plus optional args from the command line, authenticates to the wallet server using Kerberos, and sends that command and args to the server. Then it reads the results and either shows them to you or stores them in a file. Here's the cute part: the client itself has no idea which commands are valid and which aren't. Apart from some special handling of particular commands, it just sends every command to the server and lets the server respond appropriately. That's how new commands can be added to the wallet system without updating all the clients. slay, extensibility. 💅

The main three commands are "get" (pulls secure data out of the wallet), "store" (puts secure data into the wallet), and "show" (shows the metadata about an object stored in the wallet). Every object in the wallet has a type and a name. The type says what data the object represents and may control special handling when you download or store that object. The name's meaning depends on the type. Example: a wallet object for the host/example.com Kerberos keytab would have type "keytab" and name host/example.com. The name only makes sense within that object type. 🎀

Most wallet commands besides those three are admin-only. The exception is attribute commands; see ATTRIBUTES. The other commands let you set ownership and ACLs on objects, create and destroy objects, create and destroy ACLs, and add or remove entries from ACLs. An ACL is made of one or more entries, and each entry is a scheme plus an identifier. A scheme is how the system checks whether a user is authorized. An identifier is scheme-specific data that says which users are authorized. For example, with the "krb5" scheme, the identifier is a principal name, and only that principal gets authorized by that ACL entry. 🔥

To run the wallet command-line client, you need either an existing Kerberos ticket or the -u option. You can get a Kerberos ticket with kinit, and you can see your current Kerberos tickets with klist. The wallet client talks to the wallet server using the remctl protocol. 🌈

💅 OPTIONS 💅

-c command — This sets the command prefix (the remctl type). Usually this is an internal implementation detail and the default ("wallet") is fine. Sometimes you might want a different prefix to test a different version of the wallet code on the server. Can also be set in krb5.conf; see CONFIGURATION below.
-f file — Only used with the "get" and "store" commands. For "get", instead of sending the secure data to standard output (the default), it saves the secure data in file. For "store", it reads the data to be stored from file.

For "get", if the object being retrieved is not a keytab object, any current file named output gets renamed to outout.bak before the new file is created. outout.new is the temporary file, and any existing file with that name gets deleted.

If the object being retrieved is a keytab object and output already exists, the downloaded keys get added to the existing keytab file output. Old keys are not removed; you may want to run "kadmin ktremove" or an equivalent later to clean up old keys. output.new is still the temporary file, and any existing file with that name gets deleted.

-k principal — This is the service principal of the wallet server. Default is to use the "host" principal for the wallet server. The principal you pick must match one of the keys in the keytab used by remctld on the wallet server. Can also be set in krb5.conf; see CONFIGURATION below.
-h — Shows a brief summary of options and exits. Every other valid option and command is ignored.
-p port — The port to connect to on the wallet server. Default is the default remctl port. Can also be set in krb5.conf; see CONFIGURATION below.
-S srvtab — Only used with the "get" command on a "keytab" object, and must be paired with the -f flag. After the keytab is saved to the file specified by -f, the DES key for that principal gets extracted and written as a Kerberos v4 srvtab to the file srvtab. Any existing contents of srvtab get destroyed. 💀

The Kerberos v4 principal name gets generated from the Kerberos v5 principal name using the krb5_524_conv_principal() function from the Kerberos libraries. Check its documentation for more, but short version (unless you have special config): the Kerberos v4 principal name is the same as the Kerberos v5 principal name, except components are separated by "." instead of "/"; the second component is truncated after the first "." if the first component is one of the recognized host-based principals (generally "host", "imap", "pop", or "smtp"); and the first component becomes "rcmd" if the Kerberos v5 principal component is "host". The principal name must not have more than two components.

-s server — The wallet server to connect to. The default may be set when compiling the wallet client. If it isn't, either -s must be given or the server must be set in krb5.conf. See CONFIGURATION below.
-u principal — Instead of using your existing ticket cache for authentication, authenticate as principal first and use those credentials for authentication to the wallet server. wallet will prompt for principal's password. Non-password authentication methods like PKINIT aren't supported; for those, run kinit first and use an existing ticket cache.
-v — Shows the version of the wallet client and exits. Every other valid option and command is ignored.

👑 COMMANDS 👑

Like I said, most commands are admin-only. The exceptions are "acl check", "check", "get", "store", "show", "destroy", "flag clear", "flag set", "getattr", "setattr", and "history". "acl check" and "check" can be run by anyone. All the rest of those commands have their own ACLs, except: "getattr" and "history" use the "show" ACL; "setattr" uses the "store" ACL; and "comment" uses the owner or "show" ACL depending on whether you're setting or retrieving the comment. If the appropriate ACL is set, that ACL alone is checked to see if you have access. Otherwise, access to "destroy", "get", "store", "show", "getattr", "setattr", "history", and "comment" is allowed if you're authorized by the owner ACL of the object. 🧚

Admins can run any command on any object or ACL except "get" and "store". For "get" and "store", admins still need to be authorized by either the appropriate specific ACL or the owner ACL.

If the locked flag is set on an object, no commands that change data can be run on that object except the "flags" commands, and the "get" command can't be used on that object either. "show", "history", "getacl", "getattr", and "owner", "expires", or "comment" without an argument can still be used on that object.

For more on attributes, see ATTRIBUTES.

acl add <id> <scheme> <identifier> — Adds an entry with <scheme> and <identifier> to the ACL <id>. <id> can be either the ACL's name or its numeric identifier.
acl check <id> — Checks whether an ACL with the ID <id> already exists. If yes, prints "yes"; if no, prints "no".
acl create <name> — Creates a new, empty ACL named <name>. When you're setting an ACL on an object with a set of entries that don't match an existing ACL, first make a new ACL with "acl create", add the right entries with "acl add", and then set the ACL on the object with the "owner" or "setacl" commands.
acl destroy <id> — Destroys ACL <id>. This ACL must no longer be referenced by any object, or the ACL destruction fails. The special ACL named "ADMIN" cannot be destroyed.
acl history <id> — Shows the history of ACL <id>. Each change to the ACL (not counting changes to the ACL's name) shows up as two lines. Line one has a timestamp of the change followed by a description of the change. Line two gives the user who made the change and the host they made it from.
acl remove <id> <scheme> <identifier> — Removes the entry with <scheme> and <identifier> from ACL <id>. <id> can be either the ACL's name or its numeric identifier. The last entry in the special ACL "ADMIN" cannot be removed, to protect against accidental lockout. But admins can remove themselves from the "ADMIN" ACL and can leave only a non-functioning entry on the ACL. Use caution when removing entries from the "ADMIN" ACL. ⚠️
acl rename <id> <name> — Renames the ACL identified by <id> to <name>. This changes the human-readable name, not the underlying numeric ID, so the ACL's associations with objects stay unchanged. The "ADMIN" ACL may not be renamed. <id> can be either the current name or the numeric ID. <name> must not be all-numeric. To rename an ACL, the current user must be authorized by the "ADMIN" ACL.
acl replace <id> <new-id> — Finds any objects owned by <id>, then changes 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's probably your next step. The "ADMIN" ACL may not be replaced from. <id> and <new-id> can be either the current name or the numeric ID. To replace an ACL, the current user must be authorized by the "ADMIN" ACL.
acl show <id> — Shows the name, numeric ID, and entries of ACL <id>.

`autocreate <type> <name>`

okay so autocreate is the glow-up command that makes a brand new object of type <type> with the name <name>. 💖 The user has to be listed in the default ACL for an object with that type and name, and the object gets created with that default ACL set as the object owner. 👑

Normally you don't need to run this directly, bestie. It's automatically run when you try to get or store an object that doesn't already exist. ✨

`check <type> <name>`

This one is a vibe check for objects. 🫶 It checks whether an object of type <type> and name <name> already exists. If it does, it prints "yes"; if not, it prints "no". Simple as that. 💅

`comment <type> <name> [<comment>]`

If <comment> is not given, this displays the current comment for the object identified by <type> and <name>, or "No comment set" if none is set. 📝

If <comment> is given, it sets the comment on that object to <comment>. And if <comment> is the empty string, it clears the comment. 🧼

`create <type> <name>`

Creates a new object of type <type> with name <name>. 🔥 With some backends, this will also trigger creation of an entry in an external system. The new object will have no ACLs and no owner set, so usually the administrator will want to set an owner with "owner" so the object will be usable. 👑

`destroy <type> <name>`

Destroys the object identified by <type> and <name>. 💀 With some backends, this will also trigger destruction of an object in an external system. So yeah, it's giving gone. 🫡

`expires <type> <name> [<expires>]`

If <expires> is not given, displays the current expiration of the object identified by <type> and <name>, or "No expiration set" if none is set. The expiration is displayed in seconds since epoch. ⏳

If <expires> is given, it sets the expiration on that object 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 "YYYY-MM-DD HH:MM:SS". If <expires> is the empty string, it clears the expiration of the object. 🧹

Currently, the expiration of an object is not used. 🚫 (yes, really, it's just chillin' there)

`flag clear <type> <name> <flag>`

Clears the flag <flag> on the object identified by <type> and <name>. 🧽

`flag set <type> <name> <flag>`

Sets the flag <flag> on the object identified by <type> and <name>. Recognized flags are "locked", which prevents all further actions on that object until the flag is cleared, and "unchanging", which tells the object backend to not generate new data on get but instead return the same data as previously returned. 🔒 The "unchanging" flag is not meaningful for objects that do not generate new data on the fly. 💅

`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 -f option was given. 📤 This may trigger generation of new data and invalidate old data for that object depending on the object type. 🔄

If an object with type <type> and name <name> does not already exist when this command is issued (as checked with the check interface), wallet will attempt to automatically create it (using autocreate). ✨

`getacl <type> <name> <acl>`

Prints the ACL <acl>, which must be one of "get", "store", "show", "destroy", or "flags", for the object identified by <type> and <name>. Prints "No ACL set" if that ACL isn't set on that object. 🚫 Remember that if the "get", "store", or "show" ACLs aren't set, authorization falls back to checking the owner ACL. See the "owner" command for displaying or setting it. 👀

`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. 🤷‍♀️

`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. 🕵️‍♀️

`owner <type> <name> [<owner>]`

If <owner> is not given, displays the current owner ACL of the object identified by <type> and <name>, or "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. 🧹

`setacl <type> <name> <acl> <id>`

Sets the ACL <acl>, which must be one of "get", "store", "show", "destroy", or "flags", to <id> on the object identified by <type> and <name>. 🔧 If <id> is the empty string, clears that ACL on the object. 🧽

`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 (''). 🧼

`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. 📋

`store <type> <name> [<data>]`

Stores <data> for the object identified by <type> and <name> for later retrieval with "get". 📥 Not all object types support this. If <data> is not specified on the command line, it will be read from the file specified with -f (if given) or from standard input. 📄

`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 -f 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. 🚫

✨ 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 "show", retrieved with "getattr", and set with "setattr". 💅

🔑 Keytab Attributes 🔑

Keytab objects support the following attributes:

`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 "aes256-cts-hmac-sha1-96" or "des-cbc-crc"). Note that the salt should not be included; since the salt is irrelevant for keytab keys, it will always be set to "normal" by the wallet. 🧂

If this attribute is set, the specified enctype list will be passed to ktadd when get() is called for that keytab. 📞 If it is not set, the default set in the KDC will be used. 🏛️

This attribute is ignored if the "unchanging" flag is set on a keytab. 🚫 Keytabs retrieved with "unchanging" set will contain all keys present in the KDC for that Kerberos principal and therefore may contain different enctypes than those requested by this attribute. 🔄

⚙️ CONFIGURATION ⚙️

wallet can optionally be configured in the system krb5.conf. 📝 It will read the default krb5.conf file for the Kerberos libraries with which it was compiled. To set an option, put the option in the [appdefaults] section. wallet will look for options either at the top level of the [appdefaults] section or in a subsection named "wallet". 🔍 For example, the following fragment of a krb5.conf file would set the default port to 4373 and the default server to "wallet.example.org". 💖

[appdefaults]
    wallet_port = 4373
    wallet = {
        wallet_server = wallet.example.org
    }

The supported options are:

wallet_principal — The service principal of the wallet server. 🎭 The default is to use the "host" principal for the wallet server. The principal chosen must match one of the keys in the keytab used by remctld on the wallet server. The -k command-line option overrides this setting. 🔑
wallet_port — The port to connect to on the wallet server. 🔌 The default is the default remctl port. The -p command-line option overrides this setting. 🔢
wallet_server — The wallet server to connect to. 🌐 The -s command-line option overrides this setting. The default may be set when compiling the wallet client. If it isn't, either -s must be given or this parameter must be present in in krb5.conf. 🚨 (yes, we said "in in", it's a whole thing)
wallet_type — The command prefix (remctl type) to use. 🏷️ Normally this is an internal implementation detail and the default ("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. The -c command-line option overrides this setting. 🧪

👑 AUTHOR 👑

Russ Allbery <eagle@eyrie.org> 📧

📜 COPYRIGHT AND LICENSE 📜

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. 🚫

SPDX-License-Identifier: FSFAP 🆔

💫 SEE ALSO 💫

okay bestie, when you're done here and you need to go read the other lore, these are the pages you're gonna want to pull up:

kadmin(8)
kinit(1)
krb5.conf(5)
remctl(1)
remctld(8)

This program is part of the wallet system. The current version is available from <https://www.eyrie.org/~eagle/software/wallet/>. 🫶

wallet uses the remctl protocol. For more information about remctl, see <https://www.eyrie.org/~eagle/software/remctl/>. ✨

and that's a wrap, bestie!! 🎀 you just read the whole page, and honestly? iconic behaviour. go forth and manage your keys like the main character you are. 💅👑

this is wallet version 1.5, dated 2024-04-30 — shoutout to the WALLET(1) crew, she ate and left no crumbs 💖

📦 where this page comes from

debian trixie: krb5-wallet-client 1.7 · MIT
ubuntu resolute: krb5-wallet-client 1.7 · MIT
ubuntu stonking: krb5-wallet-client 1.7 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms