multipass

README

MULTIPASS - a password retrieval Go library

multipass is a library that offers multiple ways for a program to retrieve passwords. The idea is to use it in combination with command line arguments or config files that usually have a "password", "password-file" or something else option.

multipass is not a password manager or a secrets vault.

Usage

multipass (programm)

A tool for testing multipass strings and hide/reveal (HID) and encrypt/decrypt (ENC) password values.

Usage:

• multipass [--help|-h|help]
• multipass [--version|version]
• multipass PROTOCOL:VALUE
  • Returns the password for the given multipass string.
• multipass hid CLEAR_TEXT
  • Returns the obfuscated version of the password.
• multipass enc CLEAR_TEXT
  • Returns the symmetrically encrypted version of the password.
  • The symmetric key is derived from the environment variable MULTIPASS_SYMMETRIC which must be set to a multipass string:
  • MULTIPASS_SYMMETRIC=TXT:my-key multipass enc my-password
  • MULTIPASS_SYMMETRIC=TXT:my-key multipass ENC:...

multipass (library)

See https://pkg.go.dev/git.sr.ht/~kulbartsch/multipass

• TODO: For now the functions are described here, but that will be removed.

multipass (function)

Hand over a multipass-string with in the form

PROTOCOL:VALUE

hide / reveal (function)

Functions obfuscate / deobfuscate the password with the HID protocol.

Compatibility (bool)

If set to "true" the following logic applies: If the multipass-string does not match the PROTOCOL:VALUE form or the Protocol is unknown it is assumed that this is just the plain password. This offers the compatibility to the usual plain "password" option when migrating to this library.

FirstLine (bool)

FirstLine is a boolean that indicates whether only the first line of the password source should be used. This is useful for commands (CMD) or files (FIL) that return multi-line output, but only the first line is relevant. The default is "true".

RecursionDepthMax (int)

Maximum recursion depth for nested Multipass lookups, especially ENR chains. This prevents stack overflows on cyclic or overly deep inputs.

The default is 5. Applications can raise the value if they need deeper chains.

Feature (int)

Not yet implemented. Will probably never be implemented.

Bit-flags that describe which protocol features are activated. const enums matching the protocol names are provided.

Default is all active (63).

Symmetric (string)

Key source for ENC encryption/decryption.

Supported key source protocols: TXT, ENV, ENR, FIL, CMD, HID, ENC is intentionally not allowed as key source to avoid recursion.

Default is empty. The application has to set it before using ENC.

For the CLI helper, this is configured via environment variable:

MULTIPASS_SYMMETRIC=TXT:my-key multipass ENC:...
MULTIPASS_SYMMETRIC=TXT:my-key multipass enc my-password

Protocol

The PROTOCOL is always 3 letters followed by a :. The protocol is case-insensitive.

TXT – plain text

The VALUE is returned as the plain text password.

CMD – external command (program)

The stdout of the command stored in VALUE is the password. If the command returns an error, the values from stdout is ignored and an error is returned.

This can be used to receive from the pass password store or other CLI tools like Hashicorp Vault provides.

ENV – environment variable

The password is stored in the environment variable named in VALUE.

ENR – environment variable recursive

The content of the environment variable named by VALUE is expected to be a PROTOCOL:VALUE pair and is processed thru multipass again.

FIL – file

The password is stored in the file named in VALUE.

HID – hidden

VALUE is an obfuscated version of the password.

The current implementation uses a random nonce, derives a byte stream from it and XORs the password with that stream. The result is stored as URL-safe Base64 text. Because of the random nonce, the same password produces different HID values on different runs.

This is not secure, just a way to avoid that you can read it just by having a short glance at it. If you made a screenshot of the value you can easily revert it.

ENC – symmetrically encrypted

VALUE is a symmetrically encrypted password.

This is technically strong and sounds good. But now you have to hand over the password for the symmetric encryption to the multipass library. And now we have a Catch-22. But it is still better than having the password in plain text and is implemented for the sake of completeness.

The current implementation uses AES-256-GCM. The symmetric key is derived from Symmetric using SHA-256.

The VALUE format is:

v1:BASE64URL

Where BASE64URL is URL-safe Base64 over nonce || ciphertext. The nonce is random per encryption.

ENC protects confidentiality and integrity of the value, but key management is still up to the calling application.

License

LGPL V2.1 or later

Documentation

Index

• Constants
• Variables
• func Decrypt(encryptedText string) (clearText string, err error)
• func Encrypt(clearText string) (encryptedText string, err error)
• func GetAuthors() []string
• func GetStringFromCmd(cmd string) (string, error)
• func GetStringFromEnv(envVar string) (string, error)
• func GetStringFromFile(filePath string) (string, error)
• func Hide(clearText string) (hiddenText string, err error)
• func Multipass(multipassString string) (password string, err error)
• func Reveal(hiddenText string) (clearText string, err error)

Constants

const (
	ProgramName = "multipass" // programName is the canonical command name used in usage and messages.
	Description = "A password retrieval Go library and tool"
	Copyright   = "Copyright: (C) 2026  Alexander Kulbartsch"
	License     = "LGPL-2.1-or-later (GNU Lesser General Public License version 2.1 or later)"
	Source      = "https://git.sr.ht/~kulbartsch/multipass"
)

Variables

var Compatibility = true

Compatibility is a boolean that indicates whether plain text passwords without a protocol prefix are still supported. This is for compatibility with usual config files that have a "password" option. It is set to true by default, but can be changed by the caller of the library to false to disable this behavior.

var FirstLine = true

FirstLine is a boolean that indicates whether only the first line of the password source should be used. This is useful for commands (CMD) or files (FIL) that return multi-line output, but only the first line is relevant.

var Manual string

Manual is the embedded project README used for CLI help output.

var RecursionDepthMax = 5

RecursionDepthMax limits recursive Multipass resolution depth (for example ENR chains). This prevents stack overflows on long chains or loops. The default is 5, but applications can raise it if they need deeper chains.

var Symmetric string

Symmetric configures the key source for ENC encryption and decryption.

It accepts plain text keys and the TXT/ENV/ENR/FIL/CMD/HID protocols. ENC is explicitly rejected to avoid recursive key resolution.

var Version string

Version is the canonical version string, embedded from the VERSION file.

Functions

func Decrypt

func Decrypt(encryptedText string) (clearText string, err error)

Decrypt is a utility function that decrypts an ENC VALUE payload into clear text.

func Encrypt

func Encrypt(clearText string) (encryptedText string, err error)

Encrypt is a utility function that symmetrically encrypts a clear text password using the ENC protocol and returns an encoded VALUE payload.

func GetAuthors

func GetAuthors() []string

GetAuthors returns a string slice with authors

func GetStringFromCmd

func GetStringFromCmd(cmd string) (string, error)

GetStringFromCmd executes an external command and returns its output as a string.

func GetStringFromEnv

func GetStringFromEnv(envVar string) (string, error)

func GetStringFromFile

func GetStringFromFile(filePath string) (string, error)

func Hide

func Hide(clearText string) (hiddenText string, err error)

Hide is a utility function that obfuscates a clear text password using the HID protocol.

func Multipass

func Multipass(multipassString string) (password string, err error)

Multipass is the main function that retrieves a password from a given multipass string. It returns the password as a string and an error if any.

func Reveal

func Reveal(hiddenText string) (clearText string, err error)

Reveal is a utility function that deobfuscates a hidden password using the HID protocol.