1 e346be82 2022-06-29 op .\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
  2 e346be82 2022-06-29 op .\"
  3 e346be82 2022-06-29 op .\" Permission to use, copy, modify, and distribute this software for any
  4 e346be82 2022-06-29 op .\" purpose with or without fee is hereby granted, provided that the above
  5 e346be82 2022-06-29 op .\" copyright notice and this permission notice appear in all copies.
  6 e346be82 2022-06-29 op .\"
  7 e346be82 2022-06-29 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 e346be82 2022-06-29 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 e346be82 2022-06-29 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 e346be82 2022-06-29 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 e346be82 2022-06-29 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 e346be82 2022-06-29 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 e346be82 2022-06-29 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 e346be82 2022-06-29 op .Dd June 29, 2022
 15 e346be82 2022-06-29 op .Dt PLASS 1
 16 e346be82 2022-06-29 op .Os
 17 e346be82 2022-06-29 op .Sh NAME
 18 e346be82 2022-06-29 op .Nm plass
 19 e346be82 2022-06-29 op .Nd manage passwords
 20 e346be82 2022-06-29 op .Sh SYNOPSIS
 21 e346be82 2022-06-29 op .Nm
 22 e346be82 2022-06-29 op .Op Fl h
 23 e346be82 2022-06-29 op .Oo
 24 e346be82 2022-06-29 op .Cm command
 25 e346be82 2022-06-29 op .Ar argument ...
 26 e346be82 2022-06-29 op .Oc
 27 e346be82 2022-06-29 op .Sh DESCRIPTION
 28 e346be82 2022-06-29 op .Nm
 29 e346be82 2022-06-29 op is a simple password manager.
 30 e346be82 2022-06-29 op It manages paswords store in a directory tree rooted at
 31 e346be82 2022-06-29 op .Pa ~/.password-store
 32 e346be82 2022-06-29 op .Pq or at Ev PLASS_STORE ,
 33 e346be82 2022-06-29 op where every password is a single file encrypted with
 34 e346be82 2022-06-29 op .Xr gpg2 1 .
 35 e346be82 2022-06-29 op .Pp
 36 e346be82 2022-06-29 op Password entries can be referenced using the path relative to the
 37 e346be82 2022-06-29 op store directory.
 38 e346be82 2022-06-29 op The extension
 39 e346be82 2022-06-29 op .Dq \&.gpg
 40 e346be82 2022-06-29 op is optional.
 41 e346be82 2022-06-29 op .Pp
 42 e346be82 2022-06-29 op The whole store is supposed to be managed by the
 43 e346be82 2022-06-29 op .Xr got 1
 44 e346be82 2022-06-29 op version control system.
 45 e346be82 2022-06-29 op .Pp
 46 e346be82 2022-06-29 op The following commands are available:
 47 e346be82 2022-06-29 op .Bl -tag -width Ds
 48 e346be82 2022-06-29 op .It Cm cat Ar entries ...
 49 e346be82 2022-06-29 op Decrypt and print the content of the given
 50 e346be82 2022-06-29 op .Ar entries .
 51 e346be82 2022-06-29 op .It Cm find Op Ar pattern
 52 e346be82 2022-06-29 op Print one per line all the entries of the store, optionally filtered
 53 e346be82 2022-06-29 op by the given
 54 e346be82 2022-06-29 op .Ar pattern .
 55 e346be82 2022-06-29 op .It Cm gen Oo Fl nq Oc Oo Fl c Ar chars Oc Oo Fl l Ar length Oc Ar entry
 56 e346be82 2022-06-29 op Generate and persist a password for the given
 57 e346be82 2022-06-29 op .Ar entry
 58 e346be82 2022-06-29 op in the store.
 59 e346be82 2022-06-29 op .Fl c
 60 e346be82 2022-06-29 op can be used to control the characters allowed in the password
 61 e346be82 2022-06-29 op (by default
 62 e346be82 2022-06-29 op .Dq !-~
 63 e346be82 2022-06-29 op i.e. all the printable ASCII characters)
 64 e346be82 2022-06-29 op and
 65 e346be82 2022-06-29 op .Fl l
 66 e346be82 2022-06-29 op the length
 67 e346be82 2022-06-29 op .Pq 32 by default .
 68 e346be82 2022-06-29 op Unless the
 69 e346be82 2022-06-29 op .Fl q
 70 e346be82 2022-06-29 op flag is provided,
 71 e346be82 2022-06-29 op .Nm
 72 e346be82 2022-06-29 op prints the generated password.
 73 e346be82 2022-06-29 op If the
 74 e346be82 2022-06-29 op .Fl n
 75 e346be82 2022-06-29 op flag is given, the password won't be persisted.
 76 e346be82 2022-06-29 op .It Cm got Ar arguments
 77 e346be82 2022-06-29 op Execute
 78 e346be82 2022-06-29 op .Xr got 1
 79 e346be82 2022-06-29 op in the password store directory with the given
 80 e346be82 2022-06-29 op .Ar arguments .
 81 e346be82 2022-06-29 op .It Cm mv Ar from Ar to
 82 e346be82 2022-06-29 op Rename a password entry, doesn't work with directories.
 83 e346be82 2022-06-29 op .Ar from
 84 e346be82 2022-06-29 op must exists and
 85 e346be82 2022-06-29 op .Ar to
 86 e346be82 2022-06-29 op mustn't.
 87 e346be82 2022-06-29 op .It Cm rm Ar entries ...
 88 e346be82 2022-06-29 op Remove the given
 89 e346be82 2022-06-29 op .Ar entries
 90 e346be82 2022-06-29 op from the store.
 91 e346be82 2022-06-29 op .It Cm tee Oo Fl q Oc Ar entry
 92 e346be82 2022-06-29 op Prompt for a password and persist it into the store under the given
 93 e346be82 2022-06-29 op .Ar entry
 94 e346be82 2022-06-29 op name and the print it again on the standard output.
 95 e346be82 2022-06-29 op If the
 96 e346be82 2022-06-29 op .Fl q
 97 e346be82 2022-06-29 op option is given, nothing is printed to standard output.
 98 e346be82 2022-06-29 op .It Cm tog Ar arguments ...
 99 e346be82 2022-06-29 op Execute
100 e346be82 2022-06-29 op .Xr tog 1
101 e346be82 2022-06-29 op in the password store directory with the given
102 e346be82 2022-06-29 op .Ar arguments .
103 e346be82 2022-06-29 op .El
104 e346be82 2022-06-29 op .Sh CREATING A PASSWORD STORE
105 e346be82 2022-06-29 op A password store is just a normal
106 e346be82 2022-06-29 op .Xr got 1
107 e346be82 2022-06-29 op repository with a worktree checkout out in
108 e346be82 2022-06-29 op .Pa ~/.password-store
109 e346be82 2022-06-29 op .Pq or at Ev PLASS_STORE .
110 e346be82 2022-06-29 op The only restriction is that a special file called
111 e346be82 2022-06-29 op .Pa .gpg-id
112 e346be82 2022-06-29 op must exist in the root of the work tree for most
113 e346be82 2022-06-29 op .Nm
114 e346be82 2022-06-29 op commands to work.
115 e346be82 2022-06-29 op .Pp
116 e346be82 2022-06-29 op For example, a got repository and password store can be initialized as
117 e346be82 2022-06-29 op follows:
118 e346be82 2022-06-29 op .Bd -literal -offset indent
119 e346be82 2022-06-29 op $ mkdir .password-store
120 e346be82 2022-06-29 op $ echo foo@example.com > .password-store/.gpg-id
121 e346be82 2022-06-29 op $ got init git/pass.git
122 e346be82 2022-06-29 op $ got import -r git/pass.git -m 'initial import' ~/.password-store
123 e346be82 2022-06-29 op $ got checkout -E ~/git/pass.git ~/.password-store
124 e346be82 2022-06-29 op .Ed
125 e346be82 2022-06-29 op .Pp
126 e346be82 2022-06-29 op see
127 e346be82 2022-06-29 op .Xr got 1
128 e346be82 2022-06-29 op for more information.
129 e346be82 2022-06-29 op .Pp
130 e346be82 2022-06-29 op Otherwise, if a repository already exists, a password store can be
131 e346be82 2022-06-29 op checked out as:
132 e346be82 2022-06-29 op .Bd -literal -offset indent
133 e346be82 2022-06-29 op $ got checkout ~/git/pass.git ~/.password-store
134 e346be82 2022-06-29 op .Ed
135 e346be82 2022-06-29 op .Pp
136 e346be82 2022-06-29 op To migrate from
137 e346be82 2022-06-29 op .Xr pass 1 ,
138 e346be82 2022-06-29 op just delete
139 e346be82 2022-06-29 op .Pa ~/.password-store
140 e346be82 2022-06-29 op and check out it again using
141 e346be82 2022-06-29 op .Xr got 1 .
142 e346be82 2022-06-29 op .Sh ENVIRONMENT
143 e346be82 2022-06-29 op .Bl -tag -width Ds
144 e346be82 2022-06-29 op .It Ev PLASS_CHARS
145 e346be82 2022-06-29 op default range of characters to use to generate passwords.
146 e346be82 2022-06-29 op .It Ev PLASS_GOT
147 e346be82 2022-06-29 op Path to the
148 e346be82 2022-06-29 op .Xr got 1
149 e346be82 2022-06-29 op executable.
150 e346be82 2022-06-29 op .It Ev PLASS_GPG
151 e346be82 2022-06-29 op Path to the
152 e346be82 2022-06-29 op .Xr gpg2 1
153 e346be82 2022-06-29 op executable.
154 e346be82 2022-06-29 op .It Ev PLASS_LENGTH
155 e346be82 2022-06-29 op Default length for the generated passwords.
156 e346be82 2022-06-29 op .It Ev PLASS_STORE
157 e346be82 2022-06-29 op Path to the password store directory tree.
158 e346be82 2022-06-29 op .It Ev PLASS_TOG
159 e346be82 2022-06-29 op Path to the
160 e346be82 2022-06-29 op .Xr tog 1
161 e346be82 2022-06-29 op executable.
162 e346be82 2022-06-29 op .El
163 e346be82 2022-06-29 op .Sh FILES
164 e346be82 2022-06-29 op .Bl -tag -width Ds
165 e346be82 2022-06-29 op .It Pa ~/.password-store
166 e346be82 2022-06-29 op Password store used by default.
167 e346be82 2022-06-29 op .It Pa ~/.password-store/.gpg-id
168 e346be82 2022-06-29 op File containing the gpg recipient used to encrypt the passwords.
169 e346be82 2022-06-29 op .El
170 e346be82 2022-06-29 op .Sh ACKNOWLEDGEMENTS
171 e346be82 2022-06-29 op .Nm
172 e346be82 2022-06-29 op was heavily influenced by
173 e346be82 2022-06-29 op .Xr pass 1
174 e346be82 2022-06-29 op in the design, but it's a completely different implementation with
175 e346be82 2022-06-29 op different tools involved.
176 e346be82 2022-06-29 op .Sh AUTHORS
177 e346be82 2022-06-29 op .An -nosplit
178 e346be82 2022-06-29 op The
179 e346be82 2022-06-29 op .Nm
180 e346be82 2022-06-29 op utility was written by
181 e346be82 2022-06-29 op .An Omar Polo Aq Mt op@omarpolo.com .
182 e346be82 2022-06-29 op .Sh CAVEATS
183 e346be82 2022-06-29 op .Nm
184 e346be82 2022-06-29 op .Cm find
185 e346be82 2022-06-29 op output format isn't designed to handle files containing newlines.
186 e346be82 2022-06-29 op Use
187 e346be82 2022-06-29 op .Xr find 1
188 e346be82 2022-06-29 op .Fl print0
189 e346be82 2022-06-29 op or similar if it's a concern.
190 e346be82 2022-06-29 op .Pp
191 e346be82 2022-06-29 op There isn't a
192 e346be82 2022-06-29 op .Cm init
193 e346be82 2022-06-29 op sub-command, the store initialization must be performed manually.