mirror of
https://github.com/opnsense/src.git
synced 2026-02-27 03:40:37 -05:00
b077aed33b
Migrate to OpenSSL 3.0 in advance of FreeBSD 14.0. OpenSSL 1.1.1 (the version we were previously using) will be EOL as of 2023-09-11. Most of the base system has already been updated for a seamless switch to OpenSSL 3.0. For many components we've added `-DOPENSSL_API_COMPAT=0x10100000L` to CFLAGS to specify the API version, which avoids deprecation warnings from OpenSSL 3.0. Changes have also been made to avoid OpenSSL APIs that were already deprecated in OpenSSL 1.1.1. The process of updating to contemporary APIs can continue after this merge. Additional changes are still required for libarchive and Kerberos- related libraries or tools; workarounds will immediately follow this commit. Fixes are in progress in the upstream projects and will be incorporated when those are next updated. There are some performance regressions in benchmarks (certain tests in `openssl speed`) and in some OpenSSL consumers in ports (e.g. haproxy). Investigation will continue for these. Netflix's testing showed no functional regression and a rather small, albeit statistically significant, increase in CPU consumption with OpenSSL 3.0. Thanks to ngie@ and des@ for updating base system components, to antoine@ and bofh@ for ports exp-runs and port fixes/workarounds, and to Netflix and everyone who tested prior to commit or contributed to this update in other ways. PR: 271615 PR: 271656 [exp-run] Relnotes: Yes Sponsored by: The FreeBSD Foundation
328 lines
12 KiB
Groff
328 lines
12 KiB
Groff
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "UI_CREATE_METHOD 3"
|
|
.TH UI_CREATE_METHOD 3 "2023-05-30" "3.0.9" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
UI_METHOD,
|
|
UI_create_method, UI_destroy_method, UI_method_set_opener,
|
|
UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader,
|
|
UI_method_set_closer, UI_method_set_data_duplicator,
|
|
UI_method_set_prompt_constructor, UI_method_set_ex_data,
|
|
UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher,
|
|
UI_method_get_reader, UI_method_get_closer,
|
|
UI_method_get_data_duplicator, UI_method_get_data_destructor,
|
|
UI_method_get_prompt_constructor, UI_method_get_ex_data \- user
|
|
interface method creation and destruction
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/ui.h>
|
|
\&
|
|
\& typedef struct ui_method_st UI_METHOD;
|
|
\&
|
|
\& UI_METHOD *UI_create_method(const char *name);
|
|
\& void UI_destroy_method(UI_METHOD *ui_method);
|
|
\& int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
|
|
\& int UI_method_set_writer(UI_METHOD *method,
|
|
\& int (*writer) (UI *ui, UI_STRING *uis));
|
|
\& int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
|
|
\& int UI_method_set_reader(UI_METHOD *method,
|
|
\& int (*reader) (UI *ui, UI_STRING *uis));
|
|
\& int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
|
|
\& int UI_method_set_data_duplicator(UI_METHOD *method,
|
|
\& void *(*duplicator) (UI *ui, void *ui_data),
|
|
\& void (*destructor)(UI *ui, void *ui_data));
|
|
\& int UI_method_set_prompt_constructor(UI_METHOD *method,
|
|
\& char *(*prompt_constructor) (UI *ui,
|
|
\& const char
|
|
\& *object_desc,
|
|
\& const char
|
|
\& *object_name));
|
|
\& int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
|
|
\& int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
|
|
\& int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
|
|
\& int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
|
|
\& int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
|
|
\& int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
|
|
\& char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
|
|
\& (UI *, const char *, const char *);
|
|
\& void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
|
|
\& void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
|
|
\& const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
A method contains a few functions that implement the low-level of the
|
|
User Interface.
|
|
These functions are:
|
|
.IP "an opener" 4
|
|
.IX Item "an opener"
|
|
This function takes a reference to a \s-1UI\s0 and starts a session, for
|
|
example by opening a channel to a tty, or by creating a dialog box.
|
|
.IP "a writer" 4
|
|
.IX Item "a writer"
|
|
This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 String, and writes
|
|
the string where appropriate, maybe to the tty, maybe added as a field
|
|
label in a dialog box.
|
|
Note that this gets fed all strings associated with a \s-1UI,\s0 one after
|
|
the other, so care must be taken which ones it actually uses.
|
|
.IP "a flusher" 4
|
|
.IX Item "a flusher"
|
|
This function takes a reference to a \s-1UI,\s0 and flushes everything that
|
|
has been output so far.
|
|
For example, if the method builds up a dialog box, this can be used to
|
|
actually display it and accepting input ended with a pressed button.
|
|
.IP "a reader" 4
|
|
.IX Item "a reader"
|
|
This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 string and reads off
|
|
the given prompt, maybe from the tty, maybe from a field in a dialog
|
|
box.
|
|
Note that this gets fed all strings associated with a \s-1UI,\s0 one after
|
|
the other, so care must be taken which ones it actually uses.
|
|
.IP "a closer" 4
|
|
.IX Item "a closer"
|
|
This function takes a reference to a \s-1UI,\s0 and closes the session, maybe
|
|
by closing the channel to the tty, maybe by destroying a dialog box.
|
|
.PP
|
|
All of these functions are expected to return 0 on error, 1 on
|
|
success, or \-1 on out-off-band events, for example if some prompting
|
|
has been cancelled (by pressing Ctrl-C, for example).
|
|
Only the flusher or the reader are expected to return \-1.
|
|
If returned by another of the functions, it's treated as if 0 was
|
|
returned.
|
|
.PP
|
|
Regarding the writer and the reader, don't assume the former should
|
|
only write and don't assume the latter should only read.
|
|
This depends on the needs of the method.
|
|
.PP
|
|
For example, a typical tty reader wouldn't write the prompts in the
|
|
write, but would rather do so in the reader, because of the sequential
|
|
nature of prompting on a tty.
|
|
This is how the \fBUI_OpenSSL()\fR method does it.
|
|
.PP
|
|
In contrast, a method that builds up a dialog box would add all prompt
|
|
text in the writer, have all input read in the flusher and store the
|
|
results in some temporary buffer, and finally have the reader just
|
|
fetch those results.
|
|
.PP
|
|
The central function that uses these method functions is \fBUI_process()\fR,
|
|
and it does it in five steps:
|
|
.IP "1." 4
|
|
Open the session using the opener function if that one's defined.
|
|
If an error occurs, jump to 5.
|
|
.IP "2." 4
|
|
For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the writer function
|
|
if that one's defined.
|
|
If an error occurs, jump to 5.
|
|
.IP "3." 4
|
|
Flush everything using the flusher function if that one's defined.
|
|
If an error occurs, jump to 5.
|
|
.IP "4." 4
|
|
For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the reader function
|
|
if that one's defined.
|
|
If an error occurs, jump to 5.
|
|
.IP "5." 4
|
|
Close the session using the closer function if that one's defined.
|
|
.PP
|
|
\&\fBUI_create_method()\fR creates a new \s-1UI\s0 method with a given \fBname\fR.
|
|
.PP
|
|
\&\fBUI_destroy_method()\fR destroys the given \s-1UI\s0 method \fBui_method\fR.
|
|
.PP
|
|
\&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
|
|
\&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR and
|
|
\&\fBUI_method_set_closer()\fR set the five main method function to the given
|
|
function pointer.
|
|
.PP
|
|
\&\fBUI_method_set_data_duplicator()\fR sets the user data duplicator and destructor.
|
|
See \fBUI_dup_user_data\fR\|(3).
|
|
.PP
|
|
\&\fBUI_method_set_prompt_constructor()\fR sets the prompt constructor.
|
|
See \fBUI_construct_prompt\fR\|(3).
|
|
.PP
|
|
\&\fBUI_method_set_ex_data()\fR sets application specific data with a given
|
|
\&\s-1EX_DATA\s0 index.
|
|
See \fBCRYPTO_get_ex_new_index\fR\|(3) for general information on how to
|
|
get that index.
|
|
.PP
|
|
\&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
|
|
\&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
|
|
\&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
|
|
\&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
|
|
return the different method functions.
|
|
.PP
|
|
\&\fBUI_method_get_ex_data()\fR returns the application data previously stored
|
|
with \fBUI_method_set_ex_data()\fR.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fBUI_create_method()\fR returns a \s-1UI_METHOD\s0 pointer on success, \s-1NULL\s0 on
|
|
error.
|
|
.PP
|
|
\&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
|
|
\&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR,
|
|
\&\fBUI_method_set_closer()\fR, \fBUI_method_set_data_duplicator()\fR and
|
|
\&\fBUI_method_set_prompt_constructor()\fR
|
|
return 0 on success, \-1 if the given \fBmethod\fR is \s-1NULL.\s0
|
|
.PP
|
|
\&\fBUI_method_set_ex_data()\fR returns 1 on success and 0 on error (because
|
|
\&\fBCRYPTO_set_ex_data()\fR does so).
|
|
.PP
|
|
\&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
|
|
\&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
|
|
\&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
|
|
\&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
|
|
return the requested function pointer if it's set in the method,
|
|
otherwise \s-1NULL.\s0
|
|
.PP
|
|
\&\fBUI_method_get_ex_data()\fR returns a pointer to the application specific
|
|
data associated with the method.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\s-1\fBUI\s0\fR\|(3), \fBCRYPTO_get_ex_data\fR\|(3), \s-1\fBUI_STRING\s0\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
The \fBUI_method_set_data_duplicator()\fR, \fBUI_method_get_data_duplicator()\fR
|
|
and \fBUI_method_get_data_destructor()\fR functions were added in OpenSSL 1.1.1.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|