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