A prompt for ssh-agent(1) when your Yubikey needs poking
1.Dd $Mdocdate: October 15 2019$
2.Dt SSH-AGENT-CARD-PROMPT 1
3.Os
4.Sh NAME
5.Nm ssh-agent-card-prompt
6.Nd
7prompt the user when SSH key signing requests to an
8.Xr ssh-agent 1
9require tapping a physical security key (such as a YubiKey)
10.Sh SYNOPSIS
11.Nm
12.Op Fl d
13.Op Fl p Ar prompt
14.Sh DESCRIPTION
15On startup,
16.Nm
17moves the current
18.Xr ssh-agent 1
19socket (as set in the
20.Ev SSH_AUTH_SOCK
21environment variable) to a temporary location and creates a new socket at the
22location pointed to by that variable.
23.Pp
24When an SSH client connects,
25.Nm
26connects to the original
27.Xr ssh-agent 1
28process and proxies requests and responses between the two.
29.Pp
30After
31.Nm
32detects and forwards an SSH_AGENTC_SIGN_REQUEST message that appears to be for
33a PKCS key,
34.Xr ssh-agent 1
35will block while waiting for the security key to be tapped and respond to the
36request.
37At that point,
38.Nm
39will present a modal X11 window with the
40.Ar prompt
41text and information about the process that is making the agent connection,
42reminding the user to tap the key.
43.Pp
44If the Escape key is pressed while presenting the dialog, the connections to
45the client and ssh-agent are immediately dropped.
46If the security key is tapped,
47.Xr ssh-agent 1
48will send its response to
49.Nm
50which will then automatically close its X11 window.
51.Pp
52When
53.Nm
54exits, the original ssh-agent socket is moved back to the path pointed to by
55the
56.Ev SSH_AUTH_SOCK
57variable.
58.Sh CONFIGURATION
59Your security key should be configured to require touch confirmation for this
60to be of any use.
61.Pp
62For YubiKey keys, this can be done with
63.Xr yubico-piv-tool 1
64by supplying
65.Cm --touch-policy=always
66when creating/importing keys.
67.Sh OPTIONS
68.Bl -tag -width Ds
69.It Fl d
70Print debugging messages to the terminal.
71If specified twice, the contents of each message passed will be printed to the
72terminal.
73.It Fl p Ar prompt
74The text presented to the user in the modal dialog.
75Defaults to "Tap the security key to continue with signing request".
76.Sh SEE ALSO
77.Xr ssh-agent 1
78.Sh AUTHORS
79.Nm
80was written by
81.An joshua stein Aq Mt jcs@jcs.org .