Pierre Pronchery
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
300 lines
11 KiB
Plaintext
300 lines
11 KiB
Plaintext
.\" 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 "BIO_S_MEM 3"
|
|
.TH BIO_S_MEM 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"
|
|
BIO_s_secmem,
|
|
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
|
|
BIO_get_mem_ptr, BIO_new_mem_buf \- memory BIO
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/bio.h>
|
|
\&
|
|
\& const BIO_METHOD *BIO_s_mem(void);
|
|
\& const BIO_METHOD *BIO_s_secmem(void);
|
|
\&
|
|
\& BIO_set_mem_eof_return(BIO *b, int v);
|
|
\& long BIO_get_mem_data(BIO *b, char **pp);
|
|
\& BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);
|
|
\& BIO_get_mem_ptr(BIO *b, BUF_MEM **pp);
|
|
\&
|
|
\& BIO *BIO_new_mem_buf(const void *buf, int len);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fBBIO_s_mem()\fR returns the memory \s-1BIO\s0 method function.
|
|
.PP
|
|
A memory \s-1BIO\s0 is a source/sink \s-1BIO\s0 which uses memory for its I/O. Data
|
|
written to a memory \s-1BIO\s0 is stored in a \s-1BUF_MEM\s0 structure which is extended
|
|
as appropriate to accommodate the stored data.
|
|
.PP
|
|
\&\fBBIO_s_secmem()\fR is like \fBBIO_s_mem()\fR except that the secure heap is used
|
|
for buffer storage.
|
|
.PP
|
|
Any data written to a memory \s-1BIO\s0 can be recalled by reading from it.
|
|
Unless the memory \s-1BIO\s0 is read only any data read from it is deleted from
|
|
the \s-1BIO.\s0
|
|
.PP
|
|
Memory BIOs support \fBBIO_gets()\fR and \fBBIO_puts()\fR.
|
|
.PP
|
|
If the \s-1BIO_CLOSE\s0 flag is set when a memory \s-1BIO\s0 is freed then the underlying
|
|
\&\s-1BUF_MEM\s0 structure is also freed.
|
|
.PP
|
|
Calling \fBBIO_reset()\fR on a read write memory \s-1BIO\s0 clears any data in it if the
|
|
flag \s-1BIO_FLAGS_NONCLEAR_RST\s0 is not set, otherwise it just restores the read
|
|
pointer to the state it was just after the last write was performed and the
|
|
data can be read again. On a read only \s-1BIO\s0 it similarly restores the \s-1BIO\s0 to
|
|
its original state and the read only data can be read again.
|
|
.PP
|
|
\&\fBBIO_eof()\fR is true if no data is in the \s-1BIO.\s0
|
|
.PP
|
|
\&\fBBIO_ctrl_pending()\fR returns the number of bytes currently stored.
|
|
.PP
|
|
\&\fBBIO_set_mem_eof_return()\fR sets the behaviour of memory \s-1BIO\s0 \fBb\fR when it is
|
|
empty. If the \fBv\fR is zero then an empty memory \s-1BIO\s0 will return \s-1EOF\s0 (that is
|
|
it will return zero and BIO_should_retry(b) will be false. If \fBv\fR is non
|
|
zero then it will return \fBv\fR when it is empty and it will set the read retry
|
|
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
|
|
positive return value \fBv\fR should be set to a negative value, typically \-1.
|
|
.PP
|
|
\&\fBBIO_get_mem_data()\fR sets *\fBpp\fR to a pointer to the start of the memory BIOs data
|
|
and returns the total amount of data available. It is implemented as a macro.
|
|
.PP
|
|
\&\fBBIO_set_mem_buf()\fR sets the internal \s-1BUF_MEM\s0 structure to \fBbm\fR and sets the
|
|
close flag to \fBc\fR, that is \fBc\fR should be either \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0
|
|
It is a macro.
|
|
.PP
|
|
\&\fBBIO_get_mem_ptr()\fR places the underlying \s-1BUF_MEM\s0 structure in *\fBpp\fR. It is
|
|
a macro.
|
|
.PP
|
|
\&\fBBIO_new_mem_buf()\fR creates a memory \s-1BIO\s0 using \fBlen\fR bytes of data at \fBbuf\fR,
|
|
if \fBlen\fR is \-1 then the \fBbuf\fR is assumed to be nul terminated and its
|
|
length is determined by \fBstrlen\fR. The \s-1BIO\s0 is set to a read only state and
|
|
as a result cannot be written to. This is useful when some data needs to be
|
|
made available from a static area of memory in the form of a \s-1BIO.\s0 The
|
|
supplied data is read directly from the supplied buffer: it is \fBnot\fR copied
|
|
first, so the supplied area of memory must be unchanged until the \s-1BIO\s0 is freed.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Writes to memory BIOs will always succeed if memory is available: that is
|
|
their size can grow indefinitely.
|
|
.PP
|
|
Every write after partial read (not all data in the memory buffer was read)
|
|
to a read write memory \s-1BIO\s0 will have to move the unread data with an internal
|
|
copy operation, if a \s-1BIO\s0 contains a lot of data and it is read in small
|
|
chunks intertwined with writes the operation can be very slow. Adding
|
|
a buffering \s-1BIO\s0 to the chain can speed up the process.
|
|
.PP
|
|
Calling \fBBIO_set_mem_buf()\fR on a \s-1BIO\s0 created with \fBBIO_new_secmem()\fR will
|
|
give undefined results, including perhaps a program crash.
|
|
.PP
|
|
Switching the memory \s-1BIO\s0 from read write to read only is not supported and
|
|
can give undefined results including a program crash. There are two notable
|
|
exceptions to the rule. The first one is to assign a static memory buffer
|
|
immediately after \s-1BIO\s0 creation and set the \s-1BIO\s0 as read only.
|
|
.PP
|
|
The other supported sequence is to start with read write \s-1BIO\s0 then temporarily
|
|
switch it to read only and call \fBBIO_reset()\fR on the read only \s-1BIO\s0 immediately
|
|
before switching it back to read write. Before the \s-1BIO\s0 is freed it must be
|
|
switched back to the read write mode.
|
|
.PP
|
|
Calling \fBBIO_get_mem_ptr()\fR on read only \s-1BIO\s0 will return a \s-1BUF_MEM\s0 that
|
|
contains only the remaining data to be read. If the close status of the
|
|
\&\s-1BIO\s0 is set to \s-1BIO_NOCLOSE,\s0 before freeing the \s-1BUF_MEM\s0 the data pointer
|
|
in it must be set to \s-1NULL\s0 as the data pointer does not point to an
|
|
allocated memory.
|
|
.PP
|
|
Calling \fBBIO_reset()\fR on a read write memory \s-1BIO\s0 with \s-1BIO_FLAGS_NONCLEAR_RST\s0
|
|
flag set can have unexpected outcome when the reads and writes to the
|
|
\&\s-1BIO\s0 are intertwined. As documented above the \s-1BIO\s0 will be reset to the
|
|
state after the last completed write operation. The effects of reads
|
|
preceding that write operation cannot be undone.
|
|
.PP
|
|
Calling \fBBIO_get_mem_ptr()\fR prior to a \fBBIO_reset()\fR call with
|
|
\&\s-1BIO_FLAGS_NONCLEAR_RST\s0 set has the same effect as a write operation.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
There should be an option to set the maximum size of a memory \s-1BIO.\s0
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fBBIO_s_mem()\fR and \fBBIO_s_secmem()\fR return a valid memory \fB\s-1BIO_METHOD\s0\fR structure.
|
|
.PP
|
|
\&\fBBIO_set_mem_eof_return()\fR, \fBBIO_set_mem_buf()\fR and \fBBIO_get_mem_ptr()\fR
|
|
return 1 on success or a value which is less than or equal to 0 if an error occurred.
|
|
.PP
|
|
\&\fBBIO_get_mem_data()\fR returns the total number of bytes available on success,
|
|
0 if b is \s-1NULL,\s0 or a negative value in case of other errors.
|
|
.PP
|
|
\&\fBBIO_new_mem_buf()\fR returns a valid \fB\s-1BIO\s0\fR structure on success or \s-1NULL\s0 on error.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
Create a memory \s-1BIO\s0 and write some data to it:
|
|
.PP
|
|
.Vb 1
|
|
\& BIO *mem = BIO_new(BIO_s_mem());
|
|
\&
|
|
\& BIO_puts(mem, "Hello World\en");
|
|
.Ve
|
|
.PP
|
|
Create a read only memory \s-1BIO:\s0
|
|
.PP
|
|
.Vb 2
|
|
\& char data[] = "Hello World";
|
|
\& BIO *mem = BIO_new_mem_buf(data, \-1);
|
|
.Ve
|
|
.PP
|
|
Extract the \s-1BUF_MEM\s0 structure from a memory \s-1BIO\s0 and then free up the \s-1BIO:\s0
|
|
.PP
|
|
.Vb 1
|
|
\& BUF_MEM *bptr;
|
|
\&
|
|
\& BIO_get_mem_ptr(mem, &bptr);
|
|
\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
|
|
\& BIO_free(mem);
|
|
.Ve
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2000\-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>.
|