1# README: Notes about X11-based passphrase dialog for OpenSSH
2# created 1999-Nov-21 jmk
3# autodate: 2001-Feb-14 04: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  - Require 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
52x11-ssh-askpass currently uses imake and xmkmf to build.  Here's the
53procedure:
54
55  xmkmf
56  make includes
57  make
58  make install
59  make install.man
60
61x11-ssh-askpass installs by default in /usr/local/libexec/openssh/.  To
62install it somewhere else (for example, /usr/libexec/openssh/) use:
63
64  make install BINDIR=/usr/libexec/openssh
65
66Several different app-defaults files accompany x11-ssh-askpass:
67
68  SshAskpass-1337.ad    - small, dark, and gray
69  SshAskpass-NeXTish.ad - a look mildly similar to that of NEXTstep
70  SshAskpass-default.ad - the default look
71  SshAskpass-green.ad   - somewhat green
72  SshAskpass-motif.ad   - a bit like the look of the Motif toolkit
73
74If you wish a look other than the default, perform the following
75commands before building (for example):
76
77  rm -f SshAskpass_ad.h
78  make includes APP_DEFAULTS=SshAskpass-NeXTish.ad
79
80+-----------------+
81| Where To Get It |
82+-----------------+
83
84x11-ssh-askpass is available at:
85
86  http://www.jmknoble.cx/software/x11-ssh-askpass/
87
88+--------------------------+
89| Copyright, License, Etc. |
90+--------------------------+
91
92Some portions of x11-ssh-askpass are derived directly or indirectly
93from portions of xscreensaver by Jamie Zawinski <jwz@jwz.org>, while
94others are original works.
95
96The contents of the following files is taken directly, in whole or in
97part, from xscreensaver:
98
99  drawing.c
100  drawing.h
101  resources.c
102  resources.h
103
104The contents of the following files contains a limited amount of code
105(less than approximately 25%) which is derived from portions of
106xscreensaver:
107
108  x11-ssh-askpass.c
109
110The remainder of the code is an original work, including the following
111files:
112
113  dynlist.c
114  dynlist.h
115  x11-ssh-askpass.h
116  *.ad
117
118The portions derived from xscreensaver require the following notice:
119
120  xscreensaver, Copyright (c) 1991-1999 Jamie Zawinski <jwz@jwz.org>
121
122  Permission to use, copy, modify, distribute, and sell this software
123  and its documentation for any purpose is hereby granted without fee,
124  provided that the above copyright notice appear in all copies and
125  that both that copyright notice and this permission notice appear in
126  supporting documentation.  No representations are made about the
127  suitability of this software for any purpose.  It is provided "as is"
128  without express or implied warranty.
129
130The remaining portions fall under the following copyright and license:
131
132  by Jim Knoble <jmknoble@jmknoble.cx>
133  Copyright (C) 1999,2000,2001 Jim Knoble
134  
135  Permission to use, copy, modify, distribute, and sell this software
136  and its documentation for any purpose is hereby granted without fee,
137  provided that the above copyright notice appear in all copies and
138  that both that copyright notice and this permission notice appear in
139  supporting documentation.
140
141+------------+
142| Disclaimer |
143+------------+
144
145  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
146  express or implied, including but not limited to the warranties of
147  merchantability, fitness for a particular purpose and
148  noninfringement. In no event shall the author(s) be liable for any
149  claim, damages or other liability, whether in an action of contract,
150  tort or otherwise, arising from, out of or in connection with the
151  software or the use or other dealings in the software.
152
153-------- End of file --------
154