WALLET-BACKEND(8)

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

💖 WALLET-BACKEND(8) — the wallet manual, backend edition 💖

okay bestie, welcome to wallet-backend, section 8 of the wallet manual, and no cap this is the ✨glue✨ that holds the whole secure-data thing together. let's get into it 🫶

🌸 NAME 🌸

wallet-backend — the Wallet server for storing and retrieving secure data 💅

🦋 SYNOPSIS 🦋

wallet-backend [-q] command [args ...]

that's it. that's the whole vibe. one command, some args, and off you go ✨

💜 DESCRIPTION 💜

so wallet-backend is literally the interface between remctld and the wallet system. it's written to run under remctld, and it expects the authenticated identity of the remote user to show up in the REMOTE_USER environment variable. she's not guessing who you are, okay? she knows. 👑

if REMOTE_HOST isn't set, she'll fall back to REMOTE_ADDR instead, just so she's got a little extra trace info to work with. 🔍

the way it works is: she takes the command from remctld on the command line, creates a Wallet::Server object, and then calls the appropriate methods. she's basically a hype-woman for Wallet::Server — a fairly thin wrapper that translates command strings into method calls and hands you back the results. 🎀

but here's the part where she gets protective, and honestly? iconic behaviour. she checks all arguments — every single one, except for the <data> argument to the store command — and she rejects anything that doesn't match this:

^[\w_/.-]+\z

which is a fancy way of saying: only alphanumerics, underscore (_), slash (/), period (.), and hyphen (-) are permitted in arguments. that's the whole guest list and nobody else is getting in the club 🚫

this gives you some extra security on top of the checking the rest of the wallet code already does. extra layers, extra safe, we love to see it 🛡️✨

✨ OPTIONS ✨

  • --quiet, -q — if you pass this, wallet-backend will not log her actions to syslog. she's going incognito, she's keeping it lowkey, she's not leaving receipts 🙈

more of this manual is coming, bestie — don't go anywhere 💜

✨ COMMANDS ✨

okay bestie, here's the part everyone actually opens the man page for 💅 most of these commands are admin-only, meaning you gotta be on the "ADMIN" ACL to run them. The exceptions — the little VIP list of commands normal people can touch — are "acl check", "check", "get", "store", "show", "destroy", "flag clear", "flag set", "getattr", "setattr", and "history". 🫶

And out of those, "acl check" and "check" can be run by literally anyone, no ACL check at all, it's giving public library 📚. All the rest of them have their own ACLs, with a few exceptions: "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 one alone gets checked to see if you have access — nothing else, just it. Otherwise, "destroy", "get", "store", "show", "getattr", "setattr", "history", and "comment" access is permitted if you're authorized by the object's owner ACL. 🌸

Administrators can run any command on any object or ACL — main character energy — except for "get" and "store". For those two, even admins must still be authorized by either the appropriate specific ACL or the owner ACL. no cap, nobody gets a free pass on those. 👑

If the locked flag is set on an object, then no commands that change data can be run on that object at all — the only exception being the "flags" commands. And the "get" command can't be used on it either. 🚫 "show", "history", "getacl", "getattr", and "owner", "comment", or "expires" without an argument can still be used on that object though. So it's locked but not ✨muted✨.

For more information on attributes, see ATTRIBUTES.

acl add <id> <scheme> <identifier>

Adds an entry with <scheme> and <identifier> to the ACL <id>. And btw <id> can be either the name of an ACL or its numeric identifier — dealer's choice. 🎀

acl check <id>

Checks whether an ACL with the ID <id> already exists. If it does, it prints "yes"; if not, it prints "no". Simple as. ✨

acl create <name>

Makes a brand new, empty ACL named <name>. So here's the move when you're setting an ACL on an object with a set of entries that don't match any existing ACL: first acl create a new one, then acl add the appropriate entries into it, and then set it on the object using the "owner" or "setacl" commands. That's the whole pipeline bestie, don't skip steps 💅

acl destroy <id>

Destroys the ACL <id>. Important: this ACL must no longer be referenced by any object, or the destruction will just fail. And the special ACL named "ADMIN" cannot be destroyed, periodt.

acl history <id>

Shows the history of the ACL <id>. Every change to the ACL — and no, changes to the ACL's name don't count — gets represented by two lines. The first line has a timestamp of the change followed by a description of what changed, and the second line gives the user who made the change and the host they made it from. Receipts, always 📜

acl remove <id> <scheme> <identifier>

Removes 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 "ADMIN" ACL can't be removed, which exists to protect against accidental lockout 🛡️ — but heads up, administrators can remove themselves from the "ADMIN" ACL, and can leave only a non-functioning entry on the ACL. So use caution when removing entries from the "ADMIN" ACL, fr fr.

acl rename <id> <name>

Renames the ACL identified by <id> to <name>. This changes the human-readable name, not the underlying numeric ID, so all the ACL's associations with objects stay exactly the same 🦋. The "ADMIN" ACL may not be renamed. <id> may be either the current name or the numeric ID. <name> must not be all-numeric. And 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>, and then changes their ownership to <new_id> instead. <new-id> should already exist, and may already have some objects owned by it, that's fine. <id> is not deleted afterwards — though in most cases that's probably your next step, iykyk. The "ADMIN" ACL may not be replaced from. Both <id> and <new-id> may 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>

Displays the name, numeric ID, and entries of the ACL <id>. The full glow-up reveal ✨

autocreate <type> <name>

Creates a new object of type <type> with name <name>. For this one you gotta 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. 🎀

check <type> <name>

Checks whether an object of type <type> and name <name> already exists. If it does, prints "yes"; if not, prints "no". 💖

checksum file|password <name>

Returns the checksum for a file or password object. By default, a file object's checksum will be calculated using the perl function md5_hex of the Digest::MD5 module. This behavior can be overridden in the wallet configuration file. See perldoc Wallet::Config for complete details. 🔥

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

If <comment> isn't given, it 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 the object identified by <type> and <name> to <comment>. And if <comment> is the empty string, it clears the comment entirely. 🫧

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, so like, side effects are real 👀. The new object will have no ACLs and no owner set, so usually the administrator will want to then set an owner with "owner" so the object is actually usable. Don't leave it hanging bestie.

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 as well. 💀

expires <type> <name> [<date> [<time>]]

If <date> isn't given, it displays the current expiration of the object identified by <type> and <name>, or "No expiration set" if none is set. The expiration gets displayed in seconds since epoch, which is giving unix gremlin but okay.

If <date> is given, it sets the expiration on the object identified by <type> and <name> to <date> and (if given) <time>. <date> and <time> 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 <date> is the empty string, it clears the object's expiration.

Currently, the expiration of an object is not used. It's just... sitting there. Cosmetic queen. 💅

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>. The recognized flags are:

  • "locked" — prevents all further actions on that object until the flag is cleared. 🔒
  • "unchanging" — tells the object backend to not generate new data on get, but instead return the same data as previously returned.

And just so you know, the "unchanging" flag is not meaningful for objects that don't generate new data on the fly. 🦋

get <type> <name>

Prints to standard output the data associated with the object identified by <type> and <name>. Heads up though: depending on the object type, this may trigger generation of new data and invalidate old data for that object. So like, it's not always a read-only vibe check ⚠️

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. And remember, bestie: 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 — no making up attribute names, it will not slay. The attribute values, if any, are printed one per line. And if the attribute isn't set on this object, nothing is printed. silence. 🤫

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 itself, and the second line gives the user who performed the action and the host they performed it from. Full audit trail, no notes 📜✨

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

If <owner> isn't given, it 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, it sets the owner of the object identified by <type> and <name> to <owner>. If <owner> is the empty string, it clears the object's owner. 🎀

rename <type> <name> <new-name>

Renames an existing object. Currently this only supports file objects, where it renames the object itself, then the name and location of the object in the file store. 🦋

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, it 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 (''). Poof, gone 💨

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. It's the whole ✨dossier✨ bestie.

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 — some of them are just like that 🙈. If <data> isn't given as an argument, it will be read from standard input.

update <type> <name>

Prints to standard output the data associated with the object identified by <type> and <name>. If the object is one that can have changing information — like a keytab or password — then new data gets generated for that object regardless of whether there's current data or whether the unchanging flag is set. Yeah, it ignores the flag on purpose. that's the whole point of it 🔥

✨ ATTRIBUTES ✨

okay so this is where the extra info lives 💅 Object attributes are like lil bonus properties + config deets that get stored alongside objects in the wallet. They show up as part of the object data when you run show, you pull them out with getattr, and you set them with setattr. iconic little trio fr fr 🫶

🔑 Keytab Attributes 🔑

Keytab objects support the following attributes, bestie:

  • enctypes — this one restricts the generated keytab to a specific set of encryption types 🔥 The values you put here have to be enctype strings that Kerberos actually recognizes — think strings like aes256-cts-hmac-sha1-96 or des-cbc-crc. And listen: do not include the salt, okay? Since the salt is irrelevant for keytab keys, the wallet will always set it to normal. no cap.

If you set this attribute, the specified enctype list gets passed to ktadd when get() is called for that keytab. If you don't set it, then the default set in the KDC is what you get. simple as that ✨

🚨 okay important one: this attribute is ignored if the unchanging flag is set on a keytab. Keytabs retrieved with unchanging set will contain all the keys present in the KDC for that Kerberos principal, which means they may contain different enctypes than the ones you asked for in this attribute. so like... don't be surprised 😭 the unchanging flag said what it said.

💖 AUTHOR 💖

Russ Allbery <eagle@eyrie.org>

Copyright 2019 Dropbox, Inc.

Copyright 2007-2008, 2010-2013 The Board of Trustees of the Leland Stanford Junior University

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SPDX-License-Identifier: MIT

👀 SEE ALSO 👀

This program is part of the wallet system 🧚 The current version is available from <https://www.eyrie.org/~eagle/software/wallet/> — go get it bestie, it's giving legendary 🎀

and that's a wrap on the whole page!! 🌈 this version is 1.5, dated 2024-04-30 — so if you're reading this, that's the era you're in 💜 tysm for sticking around to the end, you ate fr fr 👑

📦 where this page comes from