1# README: Notes about X11-based passphrase dialog for OpenSSH
2# created 1999-Nov-21 jmk
3# autodate: 2001-Sep-16 18:07
4
5+-------------+
6| Description |
7+-------------+
8
9This is an X11-based passphrase dialog for use with OpenSSH. It is
10intended to replace the Perl/Tk-based ssh-askpass dialog and
11GNOME-based ssh-askpass dialog which formerly accompanied OpenSSH-1.2.
12These dialogs are intended to be called from the ssh-add program and
13not invoked directly.
14
15The features of x11-ssh-askpass are as follows:
16
17 - Configurable via the standard X resource mechanism
18 (/usr/lib/X11/app-defaults, ~/.Xdefaults, xrdb, etc.).
19
20 - Requires only stock X11 libraries (libXt, libX11, libSM, libICE).
21
22 - Can be configured to grab the keyboard and/or pointer (grabs the
23 keyboard by default, not the pointer).
24
25The user interface is somewhat different than most password/passphrase
26dialogs and more similar to the X11-based passphrase dialog that
27accompanies the regular SSH distribution. Instead of a text field that
28fills with asterisks or some other character as the user enters the
29passphrase, a series of LED-like areas light up one-by-one with each
30passphrase character entered, beginning from the lefthand edge of the
31dialog. When they reach the righthand edge, they go dark one-by-one
32again, and so on. This gives the user feedback that passphrase
33characters have been entered, but does not provide onlookers with a cue
34as to the length of the passphrase.
35
36Pressing the `OK' button accepts the passphrase (even if it is empty),
37which is printed on the standard output, and the dialog exits with a
38status of zero (success). Pressing the `Cancel' button discards the
39passphrase, and the dialog exits with non-zero status.
40
41The following keystrokes work as expected:
42
43 [Backspace] or [Delete] Erase previous character
44 [Control+U] or [Control+X] Erase entire passphrase
45 [Enter], [Control+M], or [Control+J] Accept passphrase (OK)
46 [Escape] Discard passphrase (Cancel)
47
48+------------+
49| Installing |
50+------------+
51
52Beginning with version 1.2.1, x11-ssh-askpass provides a 'configure'
53script to set locations to install files, etc. It's relatively
54straightforward; use './configure --help' for a full list of options.
55Most folks will probably want the default settings:
56
57 ./configure
58
59After configuring, use xmkmf and make to build and install
60x11-ssh-askpass, as follows:
61
62 xmkmf
63 make includes
64 make
65 make install
66 make install.man
67
68x11-ssh-askpass installs by default in /usr/local/libexec/; its manual
69page installs in /usr/local/man/man1/. To install them it somewhere
70else (for example, x11-ssh-askpass in /usr/libexec/openssh/ and the
71manual page in /usr/X11R6/man/man1/), use:
72
73 ./configure --libexecdir=/usr/libexec/openssh --mandir=/usr/X11R6/man/
74 xmkmf
75 make includes
76 [etc.]
77
78Several different app-defaults files accompany x11-ssh-askpass:
79
80 SshAskpass-1337.ad - small, dark, and gray
81 SshAskpass-NeXTish.ad - a look mildly similar to that of NEXTstep
82 SshAskpass-default.ad - the default look
83 SshAskpass-green.ad - somewhat green
84 SshAskpass-motif.ad - a bit like the look of the Motif toolkit
85
86You can select an app-defaults file other than the default; for
87example:
88
89 ./configure --with-app-defaults=SshAskpass-green.ad
90
91The app-defaults file installs into wherever your X11 configuration
92prefers app-defaults files to be (usually something like
93/usr/lib/X11/app-defaults/). To install the app-defaults file
94somewhere else (for example, /usr/local/lib/X11/app-defaults/), use:
95
96 ./configure --with-app-defaults-dir=/usr/local/lib/X11/app-defaults
97
98You can also decide not to install any app-defaults file:
99
100 ./configure --disable-installing-app-defaults
101
102+-----------------+
103| Where To Get It |
104+-----------------+
105
106x11-ssh-askpass is available at:
107
108 http://www.pobox.com/~jmknoble/software/x11-ssh-askpass/
109
110+--------------------------+
111| Copyright, License, Etc. |
112+--------------------------+
113
114Some portions of x11-ssh-askpass are derived directly or indirectly
115from portions of xscreensaver by Jamie Zawinski <jwz@jwz.org>, while
116others are original works.
117
118The contents of the following files is taken directly, in whole or in
119part, from xscreensaver:
120
121 drawing.c
122 drawing.h
123 resources.c
124 resources.h
125
126The contents of the following files contains a limited amount of code
127(less than approximately 25%) which is derived from portions of
128xscreensaver:
129
130 x11-ssh-askpass.c
131
132The remainder of the code is an original work, including the following
133files:
134
135 dynlist.c
136 dynlist.h
137 x11-ssh-askpass.h
138 *.ad
139
140The portions derived from xscreensaver require the following notice:
141
142 xscreensaver, Copyright (c) 1991-1999 Jamie Zawinski <jwz@jwz.org>
143
144 Permission to use, copy, modify, distribute, and sell this software
145 and its documentation for any purpose is hereby granted without fee,
146 provided that the above copyright notice appear in all copies and
147 that both that copyright notice and this permission notice appear in
148 supporting documentation. No representations are made about the
149 suitability of this software for any purpose. It is provided "as is"
150 without express or implied warranty.
151
152The remaining portions fall under the following copyright and license:
153
154 by Jim Knoble <jmknoble@pobox.com>
155 Copyright (C) 1999,2000,2001 Jim Knoble
156
157 Permission to use, copy, modify, distribute, and sell this software
158 and its documentation for any purpose is hereby granted without fee,
159 provided that the above copyright notice appear in all copies and
160 that both that copyright notice and this permission notice appear in
161 supporting documentation.
162
163+------------+
164| Disclaimer |
165+------------+
166
167 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
168 express or implied, including but not limited to the warranties of
169 merchantability, fitness for a particular purpose and
170 noninfringement. In no event shall the author(s) be liable for any
171 claim, damages or other liability, whether in an action of contract,
172 tort or otherwise, arising from, out of or in connection with the
173 software or the use or other dealings in the software.
174
175-------- End of file --------
176