1.\" x11-ssh-askpass.man 2.\" Created by Matthieu Herrb <matthieu@laas.fr> for OpenBSD 3.\" Modified by Jim Knoble <jmknoble@pobox.com> for non-OpenBSD 4.\" distribution 5.\" 6.Dd @DATE@ 7.Dt @NAME@ 1 8.Os "Version @VERSION@" 9.Sh NAME 10.Nm @NAME@ 11.Nd an X11-based pass-phrase dialog for use with OpenSSH 12.Sh SYNOPSIS 13.Nm @NAME@ 14.Op options 15.Op label 16.Sh DESCRIPTION 17.Nm 18is an X11-based pass-phrase dialog for use with OpenSSH. 19It is intended to be called from the 20.Xr ssh-add 1 21program and not invoked directly. 22.Pp 23.Nm 24supports most standard Toolkit command line arguments, with the 25exception of 26.Ar -geometry , 27.Ar -borderwidth , 28.Ar -iconic , 29.Ar -rv , 30and 31.Ar -title . 32See 33.Xr X 1 . 34.Pp 35If exactly one non-option argument is provided on the command line, it 36is displayed in the dialog instead of the default label. 37If the argument contains newline characters ('\\n'), each line of text 38is displayed on a separate line in the dialog. 39.Pp 40The features of 41.Nm 42are as follows: 43.Bl -dash -offset indent 44.It 45Configurable via the standard X resource mechanisms 46.Pa /usr/X11R6/lib/X11/app-defaults , 47.Pa ~/.Xdefaults , 48.Xr xrdb 1 , 49etc. 50.It 51Requires only stock X11 libraries (\%libXt, \%libX11, \%libSM, \%libICE). 52.It 53Can be configured to grab the keyboard and/or pointer (grabs the 54keyboard by default, not the pointer). 55.El 56.Pp 57The user interface is somewhat different than most password/pass-phrase 58dialogs and more similar to the X11-based pass-phrase dialog that 59accompanies the regular SSH distribution. 60Instead of a text field that fills with asterisks or some other 61character as the user enters the pass-phrase, a series of LED-like 62areas light up one-by-one with each pass-phrase character entered, 63beginning from the left-hand edge of the dialog. 64When they reach the right-hand edge, they go dark one-by-one 65again, and so on. 66This gives the user feedback that pass-phrase characters have been 67entered, but does not provide onlookers with a cue as to the length 68of the pass-phrase. 69.Pp 70Pressing the 71.Sq OK 72button accepts the pass-phrase (even if it is empty), 73which is printed on the standard output, and the dialog exits with a 74status of zero (success). 75Pressing the 76.Sq Cancel 77button discards the 78pass-phrase, and the dialog exits with non-zero status. 79.Pp 80The following keystrokes work as expected: 81.Bl -tag -width "[Backspace]" -offset indent -compact 82.Pp 83.It Bq Backspace 84.It Bq Delete 85Erase previous character 86.Pp 87.It Bq Control+U 88.It Bq Control+X 89Erase entire pass-phrase 90.Pp 91.It Bq Enter 92.It Bq Control+M 93.It Bq Control+J 94Accept pass-phrase (OK) 95.Pp 96.It Bq Escape 97Discard pass-phrase (Cancel) 98.El 99.Sh WIDGETS 100The main window of 101.Nm 102has the widget hierarchy indicated below. 103The widget class name is given first, followed by the instance name. 104.Bl -tag -width "Dialog" -offset indent 105.It Dialog 106dialog 107.Pp 108.Bl -tag -width "Indicator" -compact 109.It Indicator 110indicator 111.It Button 112okButton 113.It Button 114cancelButton 115.El 116.El 117.Sh RESOURCES 118The following resources are used to customize the application 119globally: 120.Bl -tag -width 2n -offset indent 121.It Cm grabKeyboard ( No class Cm GrabKeyboard ) 122.Bl -inset -compact 123.It specifies if the application should grab the keyboard. 124.It Default value: 125.Dq True . 126.El 127.It Cm grabPointer ( No class Cm GrabPointer ) 128.Bl -inset -compact 129.It specifies if the application should grab the pointer. 130.It Default value: 131.Dq False . 132.El 133.It Cm grabServer ( No class Cm GrabServer ) 134.Bl -inset -compact 135.It specifies if the application should grab the server. 136.It Default value: 137.Dq False . 138.El 139.It Cm inputTimeout ( No class Cm InputTimeout ) 140.Bl -inset -compact 141.It the number of seconds 142.Nm 143should wait for a key or 144button press before it gives up and exits. A timeout of 145.Dq 0 146means wait forever. 147.It Default value: 148.Dq 0 . 149.El 150.It Cm defaultXResolution ( No class Cm DefaultXResolution ) 151.Bl -inset -compact 152.It the number of pixels per unit length that horizontal 153spacing and width values are intended for. If the actual 154horizontal (x) resolution of the X server is significantly 155greater or less than this value, portions of the dialog, 156indicator, and button widgets are stretched or shrunk 157horizontally to take the difference into account. The value 158is a positive integer, followed by a slash 159.Cm ( / ) 160and a one- or two-character unit abbreviation. Valid units 161are inches 162.Cm ( in 163or 164.Cm i ) 165and meters 166.Cm ( m ) . 167.It Default value: 168.Dq 75/in 169(75 pixels per inch). 170.El 171.It Cm defaultYResolution ( No class Cm DefaultYResolution ) 172.Bl -inset -compact 173.It the number of pixels per unit length that vertical 174spacing and height values are intended for. If the actual 175vertical (y) resolution of the X server is significantly 176greater or less than this value, portions of the dialog, 177indicator, and button widgets are stretched or shrunk 178vertically to take the difference into account. Valid 179values are the same as for 180.Cm defaultXResolution 181above. 182.It Default value: 183.Dq 75/in 184(75 pixels per inch). 185.El 186.It Cm xResolutionFuzz ( No class Cm XResolutionFuzz ) 187.Bl -inset -compact 188.It the range of 189.Dq fuzz 190around the value of 191.Cm defaultXResolution 192beyond which some widgets will be stretched or shrunk 193horizontally to fit the current actual horizontal 194resolution. Valid values are the same as for 195.Cm defaultXResolution . 196For example, if the default X resolution is 197.Dq 75/in , 198and the X resolution fuzz is 199.Dq 50/in , 200then widgets won't be scaled horizontally unless the actual 201horizontal resolution is less than 25 pixels per inch or 202greater than 125 pixels per inch. 203.It Default value: 204.Dq 20/in 205(20 pixels per inch). 206.El 207.It Cm yResolutionFuzz ( No class Cm YResolutionFuzz ) 208.Bl -inset -compact 209.It the range of 210.Dq fuzz 211around the value of 212.Cm defaultYResolution 213beyond which some widgets will be stretched or shrunk 214vertically to fit the current actual vertical 215resolution. Valid values are the same as for 216.Cm defaultXResolution 217above. 218.It Default value: 219.Dq 20/in 220(20 pixels per inch). 221.El 222.El 223.Pp 224The following resources are recognized by the Dialog widget: 225.Bl -tag -width 2n -offset indent 226.It Cm title ( No class Cm Title ) 227The title of the application as specified to the window manager. 228.It Cm label ( No class Cm Label ) 229The label displayed above the led indicators. 230.It Cm font ( No class Cm Font ) 231The font to be used to display the label. 232.El 233.Pp 234The following Resources are recognized by the dialog, button, and 235indicator widgets and the main widget to customize the 3D appearance 236(all measurements are in pixels): 237.Bl -tag -width 2n -offset indent 238.It Cm foreground ( No class Cm Foreground ) 239The foreground color of the widget. 240This is the text color of the label for buttons and dialog and the 241color of the active led for the indicator. 242.It Cm background ( No class Cm Background ) 243The background color of the widget. 244In the case of the indicator this is the color of the inactive led. 245.It Cm topShadowColor ( No class Cm TopShadowColor ) 246The color used by the sides of the widget exposed to the light (top 247and left). 248.It Cm bottomShadowColor ( No class Cm BottomShadowColor ) 249The color used by the sides of the widget in the shadow (right and 250bottom). 251.It Cm shadowThickness ( No class Cm ShadowTickness ) 252The thickness of the 3D border of the widget. 253.It Cm borderColor ( No class Cm BorderColor ) 254The color of the border around the widget. 255.It Cm borderWidth ( No class Cm BorderWidth ) 256The width of the border around the widget. 257.It Cm horizontalSpacing ( No class Cm HorizontalSpacing ) 258The space to leave on left and right sides of the widget. 259.It Cm verticalSpacing ( No class Cm VerticalSpacing ) 260The space to leave on top and bottom sides of the widget. 261.El 262.Pp 263The following resources are recognized by the indicator widgets: 264.Bl -tag -width 2n -offset indent 265.It Cm minimumCount ( No class Cm MinimumCount ) 266The minimum number of indicators to display in the dialog. 267.It Cm maximumCount ( No class Cm MaximumCount ) 268The maximum number of indicators to display in the dialog. 269.El 270.Pp 271Each button uses the following resources to customize its label: 272.Bl -tag -width 2n -offset indent 273.It Cm label ( No class Cm Label ) 274the string to display on the button. 275.It Cm font ( No class Cm Font ) 276the font to use for this button label. 277.El 278.Sh FILES 279.Bl -tag -width "/usr/X11R6/lib/X11/app-defaults/SshAskpass" -compact 280.It Pa /usr/X11R6/lib/X11/app-defaults/SshAskpass 281.El 282.Sh SEE ALSO 283.Xr X 1 , 284.Xr ssh 1 , 285.Xr ssh-agent 1 286.Sh LICENSE 287Some portions of 288.Nm 289are derived directly or indirectly 290from portions of xscreensaver by Jamie Zawinski <jwz@jwz.org>, while 291others are original works. 292.Pp 293xscreensaver, Copyright \(co 1991-1999 Jamie Zawinski 294.Aq jwz@jwz.org 295.Pp 296Permission to use, copy, modify, distribute, and sell this software 297and its documentation for any purpose is hereby granted without fee, 298provided that the above copyright notice appear in all copies and 299that both that copyright notice and this permission notice appear in 300supporting documentation. 301No representations are made about the suitability of this software 302for any purpose. 303It is provided "as is" without express or implied warranty. 304.Pp 305The remaining portions fall under the following copyright and license: 306.Pp 307.Nm 308by Jim Knoble 309.Aq jmknoble@pobox.com 310Copyright \(co 1999,2000,2001 Jim Knoble 311.Pp 312Permission to use, copy, modify, distribute, and sell this software 313and its documentation for any purpose is hereby granted without fee, 314provided that the above copyright notice appear in all copies and 315that both that copyright notice and this permission notice appear in 316supporting documentation. 317