lpassh-add.1

.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "lpassh-add" "1" "September 02, 2020" "" ""
.hy
.SH NAME
.PP
\f[B]lpassh-add\f[R] - Unlocks OpenSSH keys using LastPass
.SH SYNOPSIS
.PP
\f[B]lpassh-add\f[R] [\f[B]-cq\f[R]] [\f[B]-t\f[R] \f[I]LIFETIME\f[R]]
[\f[I]KEY\f[R] [\f[I]KEY\f[R] [...]]]
.PP
\f[B]lpassh-add\f[R] \f[B]-h\f[R]
.PP
\f[B]lpassh-add\f[R] \f[B]-V\f[R]
.SH DESCRIPTION
.PP
\f[B]lpassh-add\f[R] adds \f[I]KEY\f[R] to the SSH authentication agent,
just as \f[B]ssh-add\f[R] would, but looks up the passphrase for
\f[I]KEY\f[R] in LastPass.
If it can\[aq]t find the passphrase there, \f[B]ssh-add\f[R] will ask
you for the passphrase instead.
.PP
If you don\[aq]t give a \f[I]KEY\f[R], it tries to add
\f[C]\[ti]/.ssh/id_rsa\f[R], \f[C]\[ti]/.ssh/id_dsa\f[R],
\f[C]\[ti]/.ssh/id_ecdsa\f[R], and \f[C]\[ti]/.ssh/id_ed25519\f[R].
.PP
If you\[aq]re not logged into LastPass and \f[C]LPASSH_ADD_USERNAME\f[R]
is set, \f[B]lpassh-add\f[R] logs you into LastPass; it also logs you
out again when it\[aq]s done.
.SH OPTIONS
.TP
-c
Confirm every use of a key.
Note, for this to work \f[C]SSH_ASKPASS\f[R] must be set when the
OpenSSH authentication agent starts.
.TP
-h
Show help.
.TP
-q
Be quieter.
.TP
-t \f[B]LIFETIME\f[R]
Automatically re-lock keys after \f[B]LIFETIME\f[R].
.TP
-V
Show version.
.PP
\f[B]-c\f[R], \f[B]-q\f[R], and \f[B]-t\f[R] are simply passed through
to \f[B]ssh-add\f[R].
See \f[B]ssh-add\f[R](1) for details about those options.
.SH WHERE TO STORE PASSPHRASES IN LASTPASS
.PP
You need to store the passphrase for each of your private SSH keys in
the \[dq]Passphrase\[dq] field of a so-called Secure Note of the type
\[dq]SSH Key\[dq].
You also need to include \[dq]ssh\[dq] in the name of that Secure Note
or in the name of the folder that you place that note in.
.PP
You can change which Secure Notes \f[B]lpassh-add\f[R] considers to
describe SSH keys by setting the environment variable
\f[C]LPASSH_ADD_PATH_REGEX\f[R].
\f[C]LPASSH_ADD_PATH_REGEX\f[R] is a basic regular expression.
If the path of a Secure Note matches this expression,
\f[B]lpassh-add\f[R] considers that Secure Note to describe an SSH key.
If you don\[aq]t set \f[C]LPASSH_ADD_PATH_REGEX\f[R] or set it to the
empty string (\[dq]\[dq]), then \f[B]lpassh-add\f[R] uses the regular
expression \[dq]ssh\[dq].
.PP
You can also make \f[B]lpassh-add\f[R] consider \f[I]every\f[R] item in
your LastPass database to describe an SSH key, namely, by setting
\f[C]LPASSH_ADD_PATH_REGEX\f[R] to a regular expression that matches any
string, \[dq].*\[dq], for example.
This is a \f[I]bad\f[R] idea.
It\[aq]s slow.
It will pass passphrases to \f[B]ssh-add\f[R] that are none of its
business.
And it will generate a lot of warnings (those are harmless, however).
.SH ENVIRONMENT
.TP
LPASSH_ADD_PATH_REGEX
A basic regular expression.
\f[B]lpassh-add\f[R] assumes that any item in your LastPass database the
path of which matches this expression describes an SSH key.
If you set this variable to a regular expression that matches any
string, \[dq].*\[dq], for example, then \f[B]lpassh-add\f[R] will assume
that \f[I]every\f[R] item in your LastPass database describes an SSH
key.
This is a \f[I]bad\f[R] idea.
(Default if not set: \[dq]ssh\[dq].)
.TP
LPASSH_ADD_USERNAME
A LastPass username.
If set, \f[B]lpassh-add\f[R] uses this username to log you into LastPass
if you aren\[aq]t logged in already.
(Default if not set: Don\[aq]t log into LastPass.)
.TP
LPASSH_ADD_AGENT_DISABLE
0 (for false) or 1 (for true).
Whether \f[B]lpassh-add\f[R] should use the LastPass agent.
Any value other than 0 or 1 triggers an error.
(Default if not set: Respect \f[C]LPASS_AGENT_DISABLE\f[R].)
.TP
LPASS_ASKPASS
Utility to ask for passphrases.
Takes precedence over \f[C]SSH_ASKPASS\f[R].
(Default if not set: Ask on teletype device of your terminal.)
.TP
SSH_ASKPASS
Utility to ask for passphrases.
Only used if \f[C]LPASS_ASKPASS\f[R] \f[I]isn\[aq]t\f[R] set.
(Default if not set: Ask on teletype device of your terminal.)
.SH SECURITY
.SS Basics
.PP
\f[B]lpassh-add\f[R] is only a shell script.
.PP
How secure a shell script is depends \f[I]a lot\f[R] on what shell
you\[aq]re running it with.
\f[B]ksh\f[R], for example, creates temporary files to handle command
substitutions (i.e., \f[C]\[ga]...\f[R]\[ga] expressions) unless the
command is built into \f[B]ksh\f[R].
As a consequence, \f[B]ksh\f[R] will write your LastPass master password
to a temporary file if you disable the LastPass agent \f[I]and\f[R] use
an askpass utility (the default is to use the LastPass agent and to
\f[I]not\f[R] use an askpass utility).
Keep in mind that your \f[B]sh\f[R] may be a symlink to \f[B]ksh\f[R].
This is just an example, however.
There are a lot of shells out there.
Use a reasonably modern and mainstream one, if possible.
Recent versions of \f[B]bash\f[R], \f[B]dash\f[R], \f[B]oksh\f[R], and
\f[B]yash\f[R] should all be fine.
.PP
You may want to read \f[B]lpassh-add\f[R] and assess the security risks
yourself.
.PP
You may also want to trace what system calls your shell makes when it
runs \f[B]lpassh-add\f[R], particularly if the shell you\[aq]re running
it with isn\[aq]t reasonably modern or mainstream.
.PP
The threat models of \f[B]ssh-add\f[R] and \f[B]lpass\f[R] apply.
.SS Behaviour
.PP
\f[B]lpassh-add\f[R] may pass the passphrases of \f[I]all\f[R] LastPass
items the path of which matches the regular expression given in
\f[C]LPASSH_ADD_PATH_REGEX\f[R] to \f[B]ssh-add\f[R].
.SS The LastPass agent
.PP
If you are using the LastPass agent, any programme that runs under your
(or the superuser\[aq]s) user ID can get a copy of your password
database by calling \f[C]lpass export\f[R] while you\[aq]re logged in.
.PP
You can use \f[B]lpassh-add\f[R] \f[I]without\f[R] using the LastPass
agent, by setting \f[C]LPASSH_ADD_AGENT_DISABLE\f[R] or
\f[C]LPASS_AGENT_DISABLE\f[R] to 1.
\f[B]lpassh-add\f[R] will still only ask you for your LastPass password
once.
.PP
That said, only do so if you know what you are doing.
Because:
.IP \[bu] 2
\f[B]lpassh-add\f[R] will then store a copy of that password in memory.
.IP \[bu] 2
If you do set \f[C]LPASS_ASKPASS\f[R] or \f[C]SSH_ASKPASS\f[R],
\f[B]lpassh-add\f[R] may write your LastPass master password to a
temporary file, depending on what shell you use to run it.
.IP \[bu] 2
If you do \f[I]not\f[R] set \f[C]LPASS_ASKPASS\f[R] or
\f[C]SSH_ASKPASS\f[R], \f[B]lpassh-add\f[R] reads your LastPass master
password from your terminal\[aq]s teletype device.
It does \f[I]not\f[R] have exclusive access to that device.
(Neither do the LastPass agent or \f[B]ssh-add\f[R] for that matter.)
.PP
Of course, every process that can invoke \f[C]lpass export\f[R] can also
change your environment so that \f[B]lpassh-add\f[R] and \f[B]lpass\f[R]
use the LastPass agent.
Disabling the LastPass agent, therefore, only improves your security if
it\[aq]s a part of a more encompassing, and highly complex, policy.
.SH EXIT STATUS
.TP
0
Success.
.TP
64
Usage error.
.TP
69
Any other error.
.TP
70
Bug.
.TP
> 128
Terminated by a signal.
.TP
Other non-zero status
Unexpected error.
.PP
\f[B]lpassh-add\f[R] may exit with other statuses on some systems or
when run by some shells (e.g., \f[B]zsh\f[R]).
However, you can safely assume that 0 indicates success and non-zero
failure.
.SH AUTHOR
.PP
Copyright 2018, 2019, 2020 Odin Kroeger
.SH SEE ALSO
.PP
\f[B]lpass\f[R](1), \f[B]ssh-add\f[R](1)
.PP
<https://github.com/odkr/lpassh-add>