Edit File by line

[0] Fix | Delete

[1] Fix | Delete

[2] Fix | Delete

* Licensed under the OpenSSL license (the "License"). You may not use

[3] Fix | Delete

* this file except in compliance with the License. You can obtain a copy

[4] Fix | Delete

* in the file LICENSE in the source distribution or at

[5] Fix | Delete

* https://www.openssl.org/source/license.html

[6] Fix | Delete

[7] Fix | Delete

[8] Fix | Delete

#ifndef HEADER_UI_H

[9] Fix | Delete

# define HEADER_UI_H

[10] Fix | Delete

[11] Fix | Delete

# include <openssl/opensslconf.h>

[12] Fix | Delete

[13] Fix | Delete

# if OPENSSL_API_COMPAT < 0x10100000L

[14] Fix | Delete

# include <openssl/crypto.h>

[15] Fix | Delete

# endif

[16] Fix | Delete

# include <openssl/safestack.h>

[17] Fix | Delete

# include <openssl/pem.h>

[18] Fix | Delete

# include <openssl/ossl_typ.h>

[19] Fix | Delete

# include <openssl/uierr.h>

[20] Fix | Delete

[21] Fix | Delete

/* For compatibility reasons, the macro OPENSSL_NO_UI is currently retained */

[22] Fix | Delete

# if OPENSSL_API_COMPAT < 0x10200000L

[23] Fix | Delete

# ifdef OPENSSL_NO_UI_CONSOLE

[24] Fix | Delete

# define OPENSSL_NO_UI

[25] Fix | Delete

# endif

[26] Fix | Delete

# endif

[27] Fix | Delete

[28] Fix | Delete

# ifdef __cplusplus

[29] Fix | Delete

extern "C" {

[30] Fix | Delete

# endif

[31] Fix | Delete

[32] Fix | Delete

[33] Fix | Delete

* All the following functions return -1 or NULL on error and in some cases

[34] Fix | Delete

* (UI_process()) -2 if interrupted or in some other way cancelled. When

[35] Fix | Delete

* everything is fine, they return 0, a positive value or a non-NULL pointer,

[36] Fix | Delete

* all depending on their purpose.

[37] Fix | Delete

[38] Fix | Delete

[39] Fix | Delete

/* Creators and destructor. */

[40] Fix | Delete

UI *UI_new(void);

[41] Fix | Delete

UI *UI_new_method(const UI_METHOD *method);

[42] Fix | Delete

void UI_free(UI *ui);

[43] Fix | Delete

[44] Fix | Delete

/*-

[45] Fix | Delete

The following functions are used to add strings to be printed and prompt

[46] Fix | Delete

strings to prompt for data. The names are UI_{add,dup}_<function>_string

[47] Fix | Delete

and UI_{add,dup}_input_boolean.

[48] Fix | Delete

[49] Fix | Delete

UI_{add,dup}_<function>_string have the following meanings:

[50] Fix | Delete

add add a text or prompt string. The pointers given to these

[51] Fix | Delete

functions are used verbatim, no copying is done.

[52] Fix | Delete

dup make a copy of the text or prompt string, then add the copy

[53] Fix | Delete

to the collection of strings in the user interface.

[54] Fix | Delete

[55] Fix | Delete

The function is a name for the functionality that the given

[56] Fix | Delete

string shall be used for. It can be one of:

[57] Fix | Delete

input use the string as data prompt.

[58] Fix | Delete

verify use the string as verification prompt. This

[59] Fix | Delete

is used to verify a previous input.

[60] Fix | Delete

info use the string for informational output.

[61] Fix | Delete

error use the string for error output.

[62] Fix | Delete

Honestly, there's currently no difference between info and error for the

[63] Fix | Delete

moment.

[64] Fix | Delete

[65] Fix | Delete

UI_{add,dup}_input_boolean have the same semantics for "add" and "dup",

[66] Fix | Delete

and are typically used when one wants to prompt for a yes/no response.

[67] Fix | Delete

[68] Fix | Delete

All of the functions in this group take a UI and a prompt string.

[69] Fix | Delete

The string input and verify addition functions also take a flag argument,

[70] Fix | Delete

a buffer for the result to end up with, a minimum input size and a maximum

[71] Fix | Delete

input size (the result buffer MUST be large enough to be able to contain

[72] Fix | Delete

the maximum number of characters). Additionally, the verify addition

[73] Fix | Delete

functions takes another buffer to compare the result against.

[74] Fix | Delete

The boolean input functions take an action description string (which should

[75] Fix | Delete

be safe to ignore if the expected user action is obvious, for example with

[76] Fix | Delete

a dialog box with an OK button and a Cancel button), a string of acceptable

[77] Fix | Delete

characters to mean OK and to mean Cancel. The two last strings are checked

[78] Fix | Delete

to make sure they don't have common characters. Additionally, the same

[79] Fix | Delete

flag argument as for the string input is taken, as well as a result buffer.

[80] Fix | Delete

The result buffer is required to be at least one byte long. Depending on

[81] Fix | Delete

the answer, the first character from the OK or the Cancel character strings

[82] Fix | Delete

will be stored in the first byte of the result buffer. No NUL will be

[83] Fix | Delete

added, so the result is *not* a string.

[84] Fix | Delete

[85] Fix | Delete

On success, the all return an index of the added information. That index

[86] Fix | Delete

is useful when retrieving results with UI_get0_result(). */

[87] Fix | Delete

int UI_add_input_string(UI *ui, const char *prompt, int flags,

[88] Fix | Delete

char *result_buf, int minsize, int maxsize);

[89] Fix | Delete

int UI_dup_input_string(UI *ui, const char *prompt, int flags,

[90] Fix | Delete

char *result_buf, int minsize, int maxsize);

[91] Fix | Delete

int UI_add_verify_string(UI *ui, const char *prompt, int flags,

[92] Fix | Delete

char *result_buf, int minsize, int maxsize,

[93] Fix | Delete

const char *test_buf);

[94] Fix | Delete

int UI_dup_verify_string(UI *ui, const char *prompt, int flags,

[95] Fix | Delete

char *result_buf, int minsize, int maxsize,

[96] Fix | Delete

const char *test_buf);

[97] Fix | Delete

int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,

[98] Fix | Delete

const char *ok_chars, const char *cancel_chars,

[99] Fix | Delete

int flags, char *result_buf);

[100] Fix | Delete

int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,

[101] Fix | Delete

const char *ok_chars, const char *cancel_chars,

[102] Fix | Delete

int flags, char *result_buf);

[103] Fix | Delete

int UI_add_info_string(UI *ui, const char *text);

[104] Fix | Delete

int UI_dup_info_string(UI *ui, const char *text);

[105] Fix | Delete

int UI_add_error_string(UI *ui, const char *text);

[106] Fix | Delete

int UI_dup_error_string(UI *ui, const char *text);

[107] Fix | Delete

[108] Fix | Delete

/* These are the possible flags. They can be or'ed together. */

[109] Fix | Delete

/* Use to have echoing of input */

[110] Fix | Delete

# define UI_INPUT_FLAG_ECHO 0x01

[111] Fix | Delete

[112] Fix | Delete

* Use a default password. Where that password is found is completely up to

[113] Fix | Delete

* the application, it might for example be in the user data set with

[114] Fix | Delete

* UI_add_user_data(). It is not recommended to have more than one input in

[115] Fix | Delete

* each UI being marked with this flag, or the application might get

[116] Fix | Delete

* confused.

[117] Fix | Delete

[118] Fix | Delete

# define UI_INPUT_FLAG_DEFAULT_PWD 0x02

[119] Fix | Delete

[120] Fix | Delete

/*-

[121] Fix | Delete

* The user of these routines may want to define flags of their own. The core

[122] Fix | Delete

* UI won't look at those, but will pass them on to the method routines. They

[123] Fix | Delete

* must use higher bits so they don't get confused with the UI bits above.

[124] Fix | Delete

* UI_INPUT_FLAG_USER_BASE tells which is the lowest bit to use. A good

[125] Fix | Delete

* example of use is this:

[126] Fix | Delete

[127] Fix | Delete

* #define MY_UI_FLAG1 (0x01 << UI_INPUT_FLAG_USER_BASE)

[128] Fix | Delete

[129] Fix | Delete

[130] Fix | Delete

# define UI_INPUT_FLAG_USER_BASE 16

[131] Fix | Delete

[132] Fix | Delete

/*-

[133] Fix | Delete

* The following function helps construct a prompt. object_desc is a

[134] Fix | Delete

* textual short description of the object, for example "pass phrase",

[135] Fix | Delete

* and object_name is the name of the object (might be a card name or

[136] Fix | Delete

* a file name.

[137] Fix | Delete

* The returned string shall always be allocated on the heap with

[138] Fix | Delete

* OPENSSL_malloc(), and need to be free'd with OPENSSL_free().

[139] Fix | Delete

[140] Fix | Delete

* If the ui_method doesn't contain a pointer to a user-defined prompt

[141] Fix | Delete

* constructor, a default string is built, looking like this:

[142] Fix | Delete

[143] Fix | Delete

* "Enter {object_desc} for {object_name}:"

[144] Fix | Delete

[145] Fix | Delete

* So, if object_desc has the value "pass phrase" and object_name has

[146] Fix | Delete

* the value "foo.key", the resulting string is:

[147] Fix | Delete

[148] Fix | Delete

* "Enter pass phrase for foo.key:"

[149] Fix | Delete

[150] Fix | Delete

char *UI_construct_prompt(UI *ui_method,

[151] Fix | Delete

const char *object_desc, const char *object_name);

[152] Fix | Delete

[153] Fix | Delete

[154] Fix | Delete

* The following function is used to store a pointer to user-specific data.

[155] Fix | Delete

* Any previous such pointer will be returned and replaced.

[156] Fix | Delete

[157] Fix | Delete

* For callback purposes, this function makes a lot more sense than using

[158] Fix | Delete

* ex_data, since the latter requires that different parts of OpenSSL or

[159] Fix | Delete

* applications share the same ex_data index.

[160] Fix | Delete

[161] Fix | Delete

* Note that the UI_OpenSSL() method completely ignores the user data. Other

[162] Fix | Delete

* methods may not, however.

[163] Fix | Delete

[164] Fix | Delete

void *UI_add_user_data(UI *ui, void *user_data);

[165] Fix | Delete

[166] Fix | Delete

* Alternatively, this function is used to duplicate the user data.

[167] Fix | Delete

* This uses the duplicator method function. The destroy function will

[168] Fix | Delete

* be used to free the user data in this case.

[169] Fix | Delete

[170] Fix | Delete

int UI_dup_user_data(UI *ui, void *user_data);

[171] Fix | Delete

/* We need a user data retrieving function as well. */

[172] Fix | Delete

void *UI_get0_user_data(UI *ui);

[173] Fix | Delete

[174] Fix | Delete

/* Return the result associated with a prompt given with the index i. */

[175] Fix | Delete

const char *UI_get0_result(UI *ui, int i);

[176] Fix | Delete

int UI_get_result_length(UI *ui, int i);

[177] Fix | Delete

[178] Fix | Delete

/* When all strings have been added, process the whole thing. */

[179] Fix | Delete

int UI_process(UI *ui);

[180] Fix | Delete

[181] Fix | Delete

[182] Fix | Delete

* Give a user interface parameterised control commands. This can be used to

[183] Fix | Delete

* send down an integer, a data pointer or a function pointer, as well as be

[184] Fix | Delete

* used to get information from a UI.

[185] Fix | Delete

[186] Fix | Delete

int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f) (void));

[187] Fix | Delete

[188] Fix | Delete

/* The commands */

[189] Fix | Delete

[190] Fix | Delete

* Use UI_CONTROL_PRINT_ERRORS with the value 1 to have UI_process print the

[191] Fix | Delete

* OpenSSL error stack before printing any info or added error messages and

[192] Fix | Delete

* before any prompting.

[193] Fix | Delete

[194] Fix | Delete

# define UI_CTRL_PRINT_ERRORS 1

[195] Fix | Delete

[196] Fix | Delete

* Check if a UI_process() is possible to do again with the same instance of

[197] Fix | Delete

* a user interface. This makes UI_ctrl() return 1 if it is redoable, and 0

[198] Fix | Delete

* if not.

[199] Fix | Delete

[200] Fix | Delete

# define UI_CTRL_IS_REDOABLE 2

[201] Fix | Delete

[202] Fix | Delete

/* Some methods may use extra data */

[203] Fix | Delete

# define UI_set_app_data(s,arg) UI_set_ex_data(s,0,arg)

[204] Fix | Delete

# define UI_get_app_data(s) UI_get_ex_data(s,0)

[205] Fix | Delete

[206] Fix | Delete

# define UI_get_ex_new_index(l, p, newf, dupf, freef) \

[207] Fix | Delete

CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_UI, l, p, newf, dupf, freef)

[208] Fix | Delete

int UI_set_ex_data(UI *r, int idx, void *arg);

[209] Fix | Delete

void *UI_get_ex_data(UI *r, int idx);

[210] Fix | Delete

[211] Fix | Delete

/* Use specific methods instead of the built-in one */

[212] Fix | Delete

void UI_set_default_method(const UI_METHOD *meth);

[213] Fix | Delete

const UI_METHOD *UI_get_default_method(void);

[214] Fix | Delete

const UI_METHOD *UI_get_method(UI *ui);

[215] Fix | Delete

const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);

[216] Fix | Delete

[217] Fix | Delete

# ifndef OPENSSL_NO_UI_CONSOLE

[218] Fix | Delete

[219] Fix | Delete

/* The method with all the built-in thingies */

[220] Fix | Delete

UI_METHOD *UI_OpenSSL(void);

[221] Fix | Delete

[222] Fix | Delete

# endif

[223] Fix | Delete

[224] Fix | Delete

[225] Fix | Delete

* NULL method. Literally does nothing, but may serve as a placeholder

[226] Fix | Delete

* to avoid internal default.

[227] Fix | Delete

[228] Fix | Delete

const UI_METHOD *UI_null(void);

[229] Fix | Delete

[230] Fix | Delete

/* ---------- For method writers ---------- */

[231] Fix | Delete

/*-

[232] Fix | Delete

A method contains a number of functions that implement the low level

[233] Fix | Delete

of the User Interface. The functions are:

[234] Fix | Delete

[235] Fix | Delete

an opener This function starts a session, maybe by opening

[236] Fix | Delete

a channel to a tty, or by opening a window.

[237] Fix | Delete

a writer This function is called to write a given string,

[238] Fix | Delete

maybe to the tty, maybe as a field label in a

[239] Fix | Delete

window.

[240] Fix | Delete

a flusher This function is called to flush everything that

[241] Fix | Delete

has been output so far. It can be used to actually

[242] Fix | Delete

display a dialog box after it has been built.

[243] Fix | Delete

a reader This function is called to read a given prompt,

[244] Fix | Delete

maybe from the tty, maybe from a field in a

[245] Fix | Delete

window. Note that it's called with all string

[246] Fix | Delete

structures, not only the prompt ones, so it must

[247] Fix | Delete

check such things itself.

[248] Fix | Delete

a closer This function closes the session, maybe by closing

[249] Fix | Delete

the channel to the tty, or closing the window.

[250] Fix | Delete

[251] Fix | Delete

All these functions are expected to return:

[252] Fix | Delete

[253] Fix | Delete

0 on error.

[254] Fix | Delete

1 on success.

[255] Fix | Delete

-1 on out-of-band events, for example if some prompting has

[256] Fix | Delete

been canceled (by pressing Ctrl-C, for example). This is

[257] Fix | Delete

only checked when returned by the flusher or the reader.

[258] Fix | Delete

[259] Fix | Delete

The way this is used, the opener is first called, then the writer for all

[260] Fix | Delete

strings, then the flusher, then the reader for all strings and finally the

[261] Fix | Delete

closer. Note that if you want to prompt from a terminal or other command

[262] Fix | Delete

line interface, the best is to have the reader also write the prompts

[263] Fix | Delete

instead of having the writer do it. If you want to prompt from a dialog

[264] Fix | Delete

box, the writer can be used to build up the contents of the box, and the

[265] Fix | Delete

flusher to actually display the box and run the event loop until all data

[266] Fix | Delete

has been given, after which the reader only grabs the given data and puts

[267] Fix | Delete

them back into the UI strings.

[268] Fix | Delete

[269] Fix | Delete

All method functions take a UI as argument. Additionally, the writer and

[270] Fix | Delete

the reader take a UI_STRING.

[271] Fix | Delete

[272] Fix | Delete

[273] Fix | Delete

[274] Fix | Delete

* The UI_STRING type is the data structure that contains all the needed info

[275] Fix | Delete

* about a string or a prompt, including test data for a verification prompt.

[276] Fix | Delete

[277] Fix | Delete

typedef struct ui_string_st UI_STRING;

[278] Fix | Delete

DEFINE_STACK_OF(UI_STRING)

[279] Fix | Delete

[280] Fix | Delete

[281] Fix | Delete

* The different types of strings that are currently supported. This is only

[282] Fix | Delete

* needed by method authors.

[283] Fix | Delete

[284] Fix | Delete

enum UI_string_types {

[285] Fix | Delete

UIT_NONE = 0,

[286] Fix | Delete

UIT_PROMPT, /* Prompt for a string */

[287] Fix | Delete

UIT_VERIFY, /* Prompt for a string and verify */

[288] Fix | Delete

UIT_BOOLEAN, /* Prompt for a yes/no response */

[289] Fix | Delete

UIT_INFO, /* Send info to the user */

[290] Fix | Delete

UIT_ERROR /* Send an error message to the user */

[291] Fix | Delete

};

[292] Fix | Delete

[293] Fix | Delete

/* Create and manipulate methods */

[294] Fix | Delete

UI_METHOD *UI_create_method(const char *name);

[295] Fix | Delete

void UI_destroy_method(UI_METHOD *ui_method);

[296] Fix | Delete

int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));

[297] Fix | Delete

int UI_method_set_writer(UI_METHOD *method,

[298] Fix | Delete

int (*writer) (UI *ui, UI_STRING *uis));

[299] Fix | Delete

int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));

[300] Fix | Delete

int UI_method_set_reader(UI_METHOD *method,

[301] Fix | Delete

int (*reader) (UI *ui, UI_STRING *uis));

[302] Fix | Delete

int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));

[303] Fix | Delete

int UI_method_set_data_duplicator(UI_METHOD *method,

[304] Fix | Delete

void *(*duplicator) (UI *ui, void *ui_data),

[305] Fix | Delete

void (*destructor)(UI *ui, void *ui_data));

[306] Fix | Delete

int UI_method_set_prompt_constructor(UI_METHOD *method,

[307] Fix | Delete

char *(*prompt_constructor) (UI *ui,

[308] Fix | Delete

const char

[309] Fix | Delete

*object_desc,

[310] Fix | Delete

const char

[311] Fix | Delete

*object_name));

[312] Fix | Delete

int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);

[313] Fix | Delete

int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);

[314] Fix | Delete

int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);

[315] Fix | Delete

int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);

[316] Fix | Delete

int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);

[317] Fix | Delete

int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);

[318] Fix | Delete

char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))

[319] Fix | Delete

(UI *, const char *, const char *);

[320] Fix | Delete

void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);

[321] Fix | Delete

void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);

[322] Fix | Delete

const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);

[323] Fix | Delete

[324] Fix | Delete

[325] Fix | Delete

* The following functions are helpers for method writers to access relevant

[326] Fix | Delete

* data from a UI_STRING.

[327] Fix | Delete

[328] Fix | Delete

[329] Fix | Delete

/* Return type of the UI_STRING */

[330] Fix | Delete

enum UI_string_types UI_get_string_type(UI_STRING *uis);

[331] Fix | Delete

/* Return input flags of the UI_STRING */

[332] Fix | Delete

int UI_get_input_flags(UI_STRING *uis);

[333] Fix | Delete

/* Return the actual string to output (the prompt, info or error) */

[334] Fix | Delete

const char *UI_get0_output_string(UI_STRING *uis);

[335] Fix | Delete

[336] Fix | Delete

* Return the optional action string to output (the boolean prompt

[337] Fix | Delete

* instruction)

[338] Fix | Delete

[339] Fix | Delete

const char *UI_get0_action_string(UI_STRING *uis);

[340] Fix | Delete

/* Return the result of a prompt */

[341] Fix | Delete

const char *UI_get0_result_string(UI_STRING *uis);

[342] Fix | Delete

int UI_get_result_string_length(UI_STRING *uis);

[343] Fix | Delete

[344] Fix | Delete

* Return the string to test the result against. Only useful with verifies.

[345] Fix | Delete

[346] Fix | Delete

const char *UI_get0_test_string(UI_STRING *uis);

[347] Fix | Delete

/* Return the required minimum size of the result */

[348] Fix | Delete

int UI_get_result_minsize(UI_STRING *uis);

[349] Fix | Delete

/* Return the required maximum size of the result */

[350] Fix | Delete

int UI_get_result_maxsize(UI_STRING *uis);

[351] Fix | Delete

/* Set the result of a UI_STRING. */

[352] Fix | Delete

int UI_set_result(UI *ui, UI_STRING *uis, const char *result);

[353] Fix | Delete

int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len);

[354] Fix | Delete

[355] Fix | Delete

/* A couple of popular utility functions */

[356] Fix | Delete

int UI_UTIL_read_pw_string(char *buf, int length, const char *prompt,

[357] Fix | Delete

int verify);

[358] Fix | Delete

int UI_UTIL_read_pw(char *buf, char *buff, int size, const char *prompt,

[359] Fix | Delete

int verify);

[360] Fix | Delete

UI_METHOD *UI_UTIL_wrap_read_pem_callback(pem_password_cb *cb, int rwflag);

[361] Fix | Delete

[362] Fix | Delete

[363] Fix | Delete

# ifdef __cplusplus

[364] Fix | Delete

}

[365] Fix | Delete

# endif

[366] Fix | Delete

#endif

[367] Fix | Delete

[368] Fix | Delete