This repository has been archived by the owner on Aug 31, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
207 lines (156 loc) · 8.44 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
PASSAGE(1) Mutineer's Guide - passage PASSAGE(1)
NAME
passage - password store utilizing age for encryption
SYNOPSIS
passage convert [-v] [DIRECTORY]
passage cp [-fr] SOURCE DESTINATION
passage edit FILE...
passage generate [-f] [-l LENGTH] FILE
passage init
passage ln [-f] TARGET DESTINATION
passage mkdir [-p] DIRECTORY...
passage mv [-f] SOURCE DESTINATION
passage rm [-fr] FILE/DIRECTORY...
passage show [-c] [FILE/DIRECTORY...]
DESCRIPTION
passage is a password store. It allows for storing passwords within a
directory, by default ${XDG_DATA_HOME}/share/passage, encrypting them
with age(1). It is based on the design of pass(1), with deviation where
pass(1) seems inconsistent or prone to feature-creep.
Goals
• Usage of age(1) rather than gpg(1). This helps to reduce the
overall amount of cruft and bloat being used in cryptography
programs, and while it’s mostly a philosophical reason, it’s the
main reason this was written.
• POSIX sh(1) compatibility. pass(1) depends on bash(1), and uses
quite a lot of bashisms, making using it with other default system
shells require a lot of changes to the code. passage doesn’t have
any non-POSIX compatible requirements, aside from age(1).
• A preference of printing easily machine-readable content by
default. pass(1)'s output tends to be geared more towards
human-readability, which can occasionally be annoying for scripting
and automated usage.
• Avoidance of piece-meal operations on password files. Most password
editing operations, other than generating a new password, should
just be done through a text editor.
• Don’t automate much by default, and don’t duplicate functionality;
for example, this means that unlike pass(1), the generate command
does not copy to the clipboard with a switch, because show -c will
do that just fine. Directories are also not automatically created
when necessary.
• Conforming to XDG specifications by default. pass(1) does not,
though it can be made to.
COMMANDS
When providing a password file as an argument, do not include the
".age" suffix.
cp [-fr] SOURCE DESTINATION
Copy a password file or directory from SOURCE to DESTINATION. -f
will allow overwriting existing files. -r will copy a directory
recursively.
convert [-v] [DIRECTORY]
Convert a pass(1) password store, DIRECTORY to a passage(1) store.
All files are decrypted using gpg(1), and then reencrypted with
age(1). If -v is specified, the gpg(1)-encrypted files will be
listed to standard error as they are converted. If unspecified,
DIRECTORY is PASSWORD_STORE_DIR (which is ~/.password-store by
default).
edit FILE
Decrypt and open FILE in your editor. The decrypted file is written
to a temporary file with owner-only read and write permissions, and
then written back to the original location.
generate [-f] [-l LENGTH] FILE
Generate a password of LENGTH characters long to FILE. If a custom
LENGTH is unspecified, the default length is 24 characters long.
The password contains alphabetical, numeric, and punctuation
symbols. If the password file already exists, it will not overwrite
it. If -f is specified, it will.
init
Create the password store directory. No arguments are taken, as the
directory and keys (if not defaults) should be set in the config or
environment (see ENVIRONMENT and FILES) anyway.
ln [-f] TARGET DESTINATION
Create a symbolic link at DESTINATION that resolves to TARGET. -f
will allow overwriting existing files and links.
mkdir [-p] DIRECTORY...
Create a directory named DIRECTORY. -p will create all parents of
the directory if they do not exist.
mv [-f] SOURCE DESTINATION
Move the SOURCE file or directory to DESTINATION. -f will allow
overwriting files.
rm [-fr] FILE/DIRECTORY...
Delete a file/directory in the password store. -f will not error
out if the file or directory doesn’t exist. -r will remove a
directory recursively.
show [-c] [FILE/DIRECTORY...]
Show a list of password files and directories, or show the contents
of a password file. Directories are listed with a trailing slash
(/) at the end of a line, files are not. Files have their ".age"
suffix removed for readability. If a path to a password file is
given, the contents of that file are printed to standard output.
If -c is specified and a password file is given, the contents are
copied to your X clipboard using xsel(1), rather than being
printed, and then the clipboard is cleared after 45 seconds. If
you provide a path to a password directory, the directory is
listed. If you provide no path of any sort, the entire password
store is listed.
VARIABLES
These variables can be set in the configuration file (see FILES). If
they are in the environment, the environment variables will take
priority.
EDITOR
The default editor used by the edit command. If not set, it
defaults to vi(1).
PASSAGE_DIR
A directory containing the password store. If not specified,
${XDG_DATA_HOME}/passage is used instead.
PASSAGE_KEY
A file path. This is the key used for encrypting passwords; your
private key. If not specified, ${XDG_CONFIG_HOME}/passage/privkey
is used.
PASSAGE_RECIPIENTS
A file path. This is the list of public keys that password files
are encrypted for; as in, this is what public keys should be able
to decrypt password files. If not specified,
${XDG_CONFIG_HOME}/passage/recipients is used.
PASSWORD_STORE_DIR
If set, this directory is used by convert, rather than pass(1)'s
own default, ~/.password-store. It’s not used if you provide
directories as arguments to convert, though. This environment
variable is also used by pass(1), thus the reason it is used here.
FILES
${PASSAGE_DIR}/*.age
Files encrypted with age(1).
${XDG_DATA_HOME}/passage
The default location of the password store. The location can be
changed with PASSAGE_DIR. By default, XDG_DATA_HOME is set to
~/.local/share.
${XDG_CONFIG_HOME}/passage/passage.conf
The default location of the configuration. Any variable in
VARIABLES can be set here. By default XDG_CONFIG_HOME is set to
~/.config.
${XDG_CONFIG_HOME}/passage/privkey
The default location of the encrypting key, or private key. The
encrypting key can be changed with PASSAGE_KEY. By default
XDG_CONFIG_HOME is set to ~/.config.
${XDG_CONFIG_HOME}/passage/recipients
The default location of the recipients list. The location can be
changed with PASSAGE_RECIPIENTS. By default XDG_CONFIG_HOME is set
to ~/.config.
NOTES
Since age(1) supports using SSH public/private key pairs for encrypting
and decrypting, you can actually just set PASSAGE_KEY to ~/.ssh/id_rsa
(or similar) and PASSAGE_RECIPIENTS to ~/.ssh/id_rsa.pub (again, or
similar), and use your SSH keys for things.
CONTRIBUTING
The canonical URL of this repository is
<https://git.mutiny.red/somasis/passage>. Submit patches and bugs to
<kylie@somas.is>.
There is also an IRC channel for passage and other projects at
<irc://irc.freenode.net/#mutiny>. Please don’t hesitate to message if
you need help.
LICENSE
passage is in the public domain.
To the extent possible under law, Kylie McClain has waived all
copyright and related or neighboring rights to this work.
<http://creativecommons.org/publicdomain/zero/1.0/>
passage 0 2020-06-26 PASSAGE(1)