Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / ui.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH ui 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
192UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
193UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
74dab6c2 194UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
984263bc
MD
195UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process,
196UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method,
197UI_set_method, UI_OpenSSL, ERR_load_UI_strings \- New User Interface
198.SH "SYNOPSIS"
74dab6c2 199.PP
984263bc
MD
200.Vb 1
201\& #include <openssl/ui.h>
202.Ve
203.Vb 2
204\& typedef struct ui_st UI;
205\& typedef struct ui_method_st UI_METHOD;
206.Ve
207.Vb 3
208\& UI *UI_new(void);
209\& UI *UI_new_method(const UI_METHOD *method);
210\& void UI_free(UI *ui);
211.Ve
212.Vb 18
213\& int UI_add_input_string(UI *ui, const char *prompt, int flags,
214\& char *result_buf, int minsize, int maxsize);
215\& int UI_dup_input_string(UI *ui, const char *prompt, int flags,
216\& char *result_buf, int minsize, int maxsize);
217\& int UI_add_verify_string(UI *ui, const char *prompt, int flags,
218\& char *result_buf, int minsize, int maxsize, const char *test_buf);
219\& int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
220\& char *result_buf, int minsize, int maxsize, const char *test_buf);
221\& int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
222\& const char *ok_chars, const char *cancel_chars,
223\& int flags, char *result_buf);
224\& int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
225\& const char *ok_chars, const char *cancel_chars,
226\& int flags, char *result_buf);
227\& int UI_add_info_string(UI *ui, const char *text);
228\& int UI_dup_info_string(UI *ui, const char *text);
229\& int UI_add_error_string(UI *ui, const char *text);
230\& int UI_dup_error_string(UI *ui, const char *text);
231.Ve
232.Vb 3
233\& /* These are the possible flags. They can be or'ed together. */
234\& #define UI_INPUT_FLAG_ECHO 0x01
235\& #define UI_INPUT_FLAG_DEFAULT_PWD 0x02
236.Ve
237.Vb 2
238\& char *UI_construct_prompt(UI *ui_method,
239\& const char *object_desc, const char *object_name);
240.Ve
241.Vb 2
242\& void *UI_add_user_data(UI *ui, void *user_data);
243\& void *UI_get0_user_data(UI *ui);
244.Ve
245.Vb 1
246\& const char *UI_get0_result(UI *ui, int i);
247.Ve
248.Vb 1
249\& int UI_process(UI *ui);
250.Ve
251.Vb 3
252\& int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
253\& #define UI_CTRL_PRINT_ERRORS 1
254\& #define UI_CTRL_IS_REDOABLE 2
255.Ve
256.Vb 4
257\& void UI_set_default_method(const UI_METHOD *meth);
258\& const UI_METHOD *UI_get_default_method(void);
259\& const UI_METHOD *UI_get_method(UI *ui);
260\& const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
261.Ve
262.Vb 1
263\& UI_METHOD *UI_OpenSSL(void);
264.Ve
265.SH "DESCRIPTION"
74dab6c2 266UI stands for User Interface, and is general purpose set of routines to
984263bc
MD
267prompt the user for text-based information. Through user-written methods
268(see ui_create(3)), prompting can be done in any way
269imaginable, be it plain text prompting, through dialog boxes or from a
270cell phone.
271.PP
74dab6c2 272All the functions work through a context of the type UI. This context
984263bc 273contains all the information needed to prompt correctly as well as a
74dab6c2 274reference to a UI_METHOD, which is an ordered vector of functions that
984263bc
MD
275carry out the actual prompting.
276.PP
74dab6c2 277The first thing to do is to create a UI with \fIUI_new()\fR or \fIUI_new_method()\fR,
984263bc
MD
278then add information to it with the UI_add or UI_dup functions. Also,
279user-defined random data can be passed down to the underlying method
74dab6c2 280through calls to UI_add_user_data. The default UI method doesn't care
984263bc
MD
281about these data, but other methods might. Finally, use \fIUI_process()\fR
282to actually perform the prompting and \fIUI_get0_result()\fR to find the result
283to the prompt.
284.PP
74dab6c2 285A UI can contain more than one prompt, which are performed in the given
984263bc
MD
286sequence. Each prompt gets an index number which is returned by the
287UI_add and UI_dup functions, and has to be used to get the corresponding
288result with \fIUI_get0_result()\fR.
289.PP
290The functions are as follows:
291.PP
74dab6c2
JR
292\fIUI_new()\fR creates a new UI using the default UI method. When done with
293this UI, it should be freed using \fIUI_free()\fR.
984263bc 294.PP
74dab6c2
JR
295\fIUI_new_method()\fR creates a new UI using the given UI method. When done with
296this UI, it should be freed using \fIUI_free()\fR.
984263bc 297.PP
74dab6c2 298\fIUI_OpenSSL()\fR returns the built-in UI method (note: not the default one,
984263bc
MD
299since the default can be changed. See further on). This method is the
300most machine/OS dependent part of OpenSSL and normally generates the
301most problems when porting.
302.PP
74dab6c2 303\fIUI_free()\fR removes a UI from memory, along with all other pieces of memory
984263bc
MD
304that's connected to it, like duplicated input strings, results and others.
305.PP
74dab6c2 306\fIUI_add_input_string()\fR and \fIUI_add_verify_string()\fR add a prompt to the UI,
984263bc
MD
307as well as flags and a result buffer and the desired minimum and maximum
308sizes of the result. The given information is used to prompt for
309information, for example a password, and to verify a password (i.e. having
310the user enter it twice and check that the same string was entered twice).
74dab6c2 311\fIUI_add_verify_string()\fR takes and extra argument that should be a pointer
984263bc
MD
312to the result buffer of the input string that it's supposed to verify, or
313verification will fail.
314.PP
74dab6c2 315\fIUI_add_input_boolean()\fR adds a prompt to the UI that's supposed to be answered
984263bc
MD
316in a boolean way, with a single character for yes and a different character
317for no. A set of characters that can be used to cancel the prompt is given
318as well. The prompt itself is really divided in two, one part being the
319descriptive text (given through the \fIprompt\fR argument) and one describing
320the possible answers (given through the \fIaction_desc\fR argument).
321.PP
74dab6c2 322\fIUI_add_info_string()\fR and \fIUI_add_error_string()\fR add strings that are shown at
984263bc
MD
323the same time as the prompt for extra information or to show an error string.
324The difference between the two is only conceptual. With the builtin method,
325there's no technical difference between them. Other methods may make a
326difference between them, however.
327.PP
74dab6c2
JR
328The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for
329\fIUI_add_input_string()\fR and will have the users response be echoed (when
984263bc 330prompting for a password, this flag should obviously not be used, and
74dab6c2
JR
331UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some
332sort will be used (completely depending on the application and the UI
984263bc
MD
333method).
334.PP
74dab6c2
JR
335\fIUI_dup_input_string()\fR, \fIUI_dup_verify_string()\fR, \fIUI_dup_input_boolean()\fR,
336\fIUI_dup_info_string()\fR and \fIUI_dup_error_string()\fR are basically the same
984263bc
MD
337as their UI_add counterparts, except that they make their own copies
338of all strings.
339.PP
74dab6c2 340\fIUI_construct_prompt()\fR is a helper function that can be used to create
984263bc
MD
341a prompt from two pieces of information: an description and a name.
342The default constructor (if there is none provided by the method used)
74dab6c2
JR
343creates a string \*(L"Enter \fIdescription\fR for \fIname\fR:\*(R". With the
344description \*(L"pass phrase\*(R" and the file name \*(L"foo.key\*(R", that becomes
345\*(L"Enter pass phrase for foo.key:\*(R". Other methods may create whatever
984263bc
MD
346string and may include encodings that will be processed by the other
347method functions.
348.PP
74dab6c2
JR
349\fIUI_add_user_data()\fR adds a piece of memory for the method to use at any
350time. The builtin UI method doesn't care about this info. Note that several
984263bc
MD
351calls to this function doesn't add data, it replaces the previous blob
352with the one given as argument.
353.PP
74dab6c2
JR
354\fIUI_get0_user_data()\fR retrieves the data that has last been given to the
355UI with \fIUI_add_user_data()\fR.
984263bc 356.PP
74dab6c2 357\fIUI_get0_result()\fR returns a pointer to the result buffer associated with
984263bc
MD
358the information indexed by \fIi\fR.
359.PP
74dab6c2 360\fIUI_process()\fR goes through the information given so far, does all the printing
984263bc
MD
361and prompting and returns.
362.PP
74dab6c2
JR
363\fIUI_ctrl()\fR adds extra control for the application author. For now, it
364understands two commands: UI_CTRL_PRINT_ERRORS, which makes \fIUI_process()\fR
365print the OpenSSL error stack as part of processing the UI, and
366UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can
984263bc
MD
367be used again or not.
368.PP
74dab6c2 369\fIUI_set_default_method()\fR changes the default UI method to the one given.
984263bc 370.PP
74dab6c2 371\fIUI_get_default_method()\fR returns a pointer to the current default UI method.
984263bc 372.PP
74dab6c2 373\fIUI_get_method()\fR returns the UI method associated with a given UI.
984263bc 374.PP
74dab6c2 375\fIUI_set_method()\fR changes the UI method associated with a given UI.
984263bc 376.SH "SEE ALSO"
984263bc
MD
377ui_create(3), ui_compat(3)
378.SH "HISTORY"
74dab6c2 379The UI section was first introduced in OpenSSL 0.9.7.
984263bc 380.SH "AUTHOR"
984263bc
MD
381Richard Levitte (richard@levitte.org) for the OpenSSL project
382(http://www.openssl.org).
74dab6c2
JR
383
384.rn }` ''
385.IX Title "ui 3"
386.IX Name "UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
387UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
388UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
389UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
390UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process,
391UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method,
392UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface"
393
394.IX Header "NAME"
395
396.IX Header "SYNOPSIS"
397
398.IX Header "DESCRIPTION"
399
400.IX Header "SEE ALSO"
401
402.IX Header "HISTORY"
403
404.IX Header "AUTHOR"
405