Other than that, provide a description above this comment if there isn't one already
-If this fixes a github issue, make sure to have a line saying 'Fixes #XXXX' (without quotes) in the commit message.
+If this fixes a GitHub issue, make sure to have a line saying 'Fixes #XXXX' (without quotes) in the commit message.
-->
##### Checklist
### Windows
If you are using Visual Studio, open a Developer Command Prompt and
-and issue the following commands to build OpenSSL.
+issue the following commands to build OpenSSL.
$ perl Configure
$ nmake
For security reasons the default system location is by default not writable
for unprivileged users. So for the final installation step administrative
privileges are required. The default system location and the procedure to
-obtain administrative privileges depends on the operating sytem.
+obtain administrative privileges depends on the operating system.
It is recommended to compile and test OpenSSL with normal user privileges
and use administrative privileges only for the final installation step.
Enable and Disable Features
---------------------------
-Feature options always come in pairs, an option to enable feature `xxxx`, and
-and option to disable it:
+Feature options always come in pairs, an option to enable feature
+`xxxx`, and an option to disable it:
[ enable-xxxx | no-xxxx ]
### threads
Build with support for multi-threaded applications. Most platforms will enable
-this by default. However if on a platform where this is not the case then this
+this by default. However, if on a platform where this is not the case then this
will usually require additional system-dependent options!
See [Notes on multi-threading](#notes-on-multi-threading) below.
Only install the OpenSSL man pages (Unix only).
install_html_docs
- Only install the OpenSSL html documentation.
+ Only install the OpenSSL HTML documentation.
list-tests
Prints a list of all the self test names.
The seeding method can be configured using the `--with-rand-seed` option,
which can be used to specify a comma separated list of seed methods.
-However in most cases OpenSSL will choose a suitable default method,
+However, in most cases OpenSSL will choose a suitable default method,
so it is not necessary to explicitly provide this option. Note also
that not all methods are available on all platforms.
will not be accidentially used.
* The algorithm specific public key command line applications have
been deprecated. These include dhparam, gendsa and others. The pkey
- alternatives should be used intead: pkey, pkeyparam and genpkey.
+ alternatives should be used instead: pkey, pkeyparam and genpkey.
* X509 certificates signed using SHA1 are no longer allowed at security
level 1 or higher. The default security level for TLS is 1, so
certificates signed using SHA1 are by default no longer trusted to
* Removed the heartbeat message in DTLS feature.
* Added EVP_KDF, an EVP layer KDF API, and a generic EVP_PKEY to EVP_KDF
bridge.
- * All of the low level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224,
+ * All of the low-level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224,
SHA256, SHA384, SHA512 and Whirlpool digest functions have been
deprecated.
- * All of the low level AES, Blowfish, Camellia, CAST, DES, IDEA, RC2,
+ * All of the low-level AES, Blowfish, Camellia, CAST, DES, IDEA, RC2,
RC4, RC5 and SEED cipher functions have been deprecated.
- * All of the low level DH, DSA, ECDH, ECDSA and RSA public key functions
+ * All of the low-level DH, DSA, ECDH, ECDSA and RSA public key functions
have been deprecated.
* SSL 3, TLS 1.0, TLS 1.1, and DTLS 1.0 only work at security level 0.
Known issues in OpenSSL 1.0.0m:
* EAP-FAST and other applications using tls_session_secret_cb
- wont resume sessions. Fixed in 1.0.0n-dev
+ won't resume sessions. Fixed in 1.0.0n-dev
* Compilation failure of s3_pkt.c on some platforms due to missing
`<limits.h>` include. Fixed in 1.0.0n-dev
* Enhanced chain verification using key identifiers.
* New sign and verify options to 'dgst' application.
* Support for DER and PEM encoded messages in 'smime' application.
- * New 'rsautl' application, low level RSA utility.
+ * New 'rsautl' application, low-level RSA utility.
* MD4 now included.
* Bugfix for SSL rollback padding check.
* Support for external crypto devices [1].
* BIGNUM library bug fixes
* Faster DSA parameter generation
* Enhanced support for Alpha Linux
- * Experimental MacOS support
+ * Experimental macOS support
### Major changes between OpenSSL 0.9.3 and OpenSSL 0.9.4 [9 Aug 1999]
-------------------
Beside basic tools like perl and make you'll need to download the Android
- NDK. It's available for Linux, Mac OS X and Windows, but only Linux
- version was actually tested. There is no reason to believe that Mac OS X
+ NDK. It's available for Linux, macOS and Windows, but only Linux
+ version was actually tested. There is no reason to believe that macOS
wouldn't work. And as for Windows, it's unclear which "shell" would be
suitable, MSYS2 might have best chances. NDK version should play lesser
role, the goal is to support a range of most recent versions.
An ANSI C compiled is needed among other things. This means that
VAX C is not and will not be supported.
- We have only tested with DEC C (a.k.a HP VMS C / VSI C) and require
+ We have only tested with DEC C (aka HP VMS C / VSI C) and require
version 7.1 or later. Compiling with a different ANSI C compiler may
require some work.
For this option you can use Cygwin.
- Visual C++ native builds, a.k.a. VC-*
+ Visual C++ native builds, aka VC-*
=====================================
Requirement details
is, of course, to choose a different set of directories by using
--prefix and --openssldir when configuring.
- Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP
+ Special notes for Universal Windows Platform builds, aka VC-*-UWP
--------------------------------------------------------------------
- UWP targets only support building the static and dynamic libraries.
MSYS2 provides GNU tools, a Unix-like command prompt,
and a UNIX compatibility layer for applications.
- However in this context it is only used for building OpenSSL.
+ However, in this context it is only used for building OpenSSL.
The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
Requirement details
B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa>
in ascending index order. The index position, within the sparse array,
of each item is passed as the first argument to the leaf function and a
-pointer to the associated value is is passed as the second argument.
+pointer to the associated value is passed as the second argument.
B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in
I<sa> in ascending index order. The index position, within the sparse
=head1 DESCRIPTION
These functions convert OpenSSL objects to and from their ASN.1/string
-representation. This function is used for B<X509v3> extentions.
+representation. This function is used for B<X509v3> extensions.
=head1 NOTES
=head1 DESCRIPTION
OpenSSL contains an internal small DER reading and writing library,
-as an alternative to the publically known i2d and d2i functions. It's
+as an alternative to the publicly known i2d and d2i functions. It's
solely constituted of functions that work as building blocks to create
more similar functions to encode and decode larger structures.
r INTEGER,
s INTEGER }
-With the DER library, this is the correspoding code, given two OpenSSL
+With the DER library, this is the corresponding code, given two OpenSSL
B<BIGNUM>s I<r> and I<s>:
int ok = DER_w_begin_sequence(pkt, -1)
=for comment "uses" could as well be "abuses"...
-It can contain the legacy form of keys -- i.e. pointers to the low
-level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
+It can contain the legacy form of keys -- i.e. pointers to the low-level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
provided form of keys -- i.e. pointers to provider side key data.
Those two forms are mutually exclusive; an B<EVP_PKEY> instance can't
contain both a key in legacy form and in provided form. Regardless of
-form, this key is commonly refered to as the "origin".
+form, this key is commonly referred to as the "origin".
An B<EVP_PKEY> also contains a cache of provider side copies of the
key, each adapted for the provider that is going to use that copy to
For OpenSSL::Template documentation,
C<perldoc -o man util/perl/OpenSSL/Template.pm>
-L<Text::Temlate|https://metacpan.org/pod/Text::Template>
+L<Text::Template|https://metacpan.org/pod/Text::Template>
=head1 COPYRIGHT
=item B<-noemailDN>
The DN of a certificate can contain the EMAIL field if present in the
-request DN, however it is good policy just having the e-mail set into
+request DN, however, it is good policy just having the e-mail set into
the altName extension of the certificate. When this option is set the
EMAIL field is removed from the certificate' subject and set only in
the, eventually present, extensions. The B<email_in_dn> keyword can be
For CMP client invocations, in particular for certificate enrollment,
usually many parameters need to be set, which is tedious and error-prone to do
on the command line.
-Therefore the client offers the possibility to read
+Therefore, the client offers the possibility to read
options from sections of the OpenSSL config file, usually called B<openssl.cnf>.
The values found there can still be extended and even overridden by any
subsequently loaded sections and on the command line.
See L<openssl(1)/Format Options> for details.
Private keys are a sequence of B<ASN.1 INTEGERS>: the version (zero), B<p>,
-B<q>, B<g>, and the public and and private key components. Public keys
+B<q>, B<g>, and the public and private key components. Public keys
are a B<SubjectPublicKeyInfo> structure with the B<DSA> type.
The B<PEM> format also accepts PKCS#8 data.
All the block ciphers normally use PKCS#5 padding, also known as standard
block padding. This allows a rudimentary integrity or password check to
-be performed. However since the chance of random data passing the test
+be performed. However, since the chance of random data passing the test
is better than 1 in 256 it isn't a very good test.
If padding is disabled then the input data must be a multiple of the cipher
encryption purposes but arbitrary length keys for signing. The B<-keysig>
option marks the key for signing only. Signing only keys can be used for
S/MIME signing, authenticode (ActiveX control signing) and SSL client
-authentication, however due to a bug only MSIE 5.0 and later support
+authentication, however, due to a bug only MSIE 5.0 and later support
the use of signing only keys for SSL client authentication.
=item B<-macalg> I<digest>
Test vectors from this PKCS#5 v2.0 implementation were posted to the
pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
counts, several people confirmed that they could decrypt the private
-keys produced and Therefore it can be assumed that the PKCS#5 v2.0
+keys produced and therefore, it can be assumed that the PKCS#5 v2.0
implementation is reasonably accurate at least as far as these
algorithms are concerned.
=head1 DESCRIPTION
-This command can be used to perform low level public key
+This command can be used to perform low-level public key
operations using any supported algorithm.
=head1 OPTIONS
with the specified proxy using basic (base64) authentication.
NB: Basic authentication is insecure; the credentials are sent to the proxy
in easily reversible base64 encoding before any TLS/SSL session is established.
-Therefore these credentials are easily recovered by anyone able to sniff/trace
+Therefore, these credentials are easily recovered by anyone able to sniff/trace
the network. Use with caution.
=item B<-proxy_pass> I<arg>
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using this command, the CA list can be viewed
-and checked. However some servers only request client authentication
+and checked. However, some servers only request client authentication
after a specific URL is requested. To obtain the list in this case it
is necessary to use the B<-prexit> option and send an HTTP request
for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
option it will not be used unless the server specifically requests
-a client certificate. Therefore merely including a client certificate
+a client certificate. Therefore, merely including a client certificate
on the command line is no guarantee that the certificate works.
If there are problems verifying a server certificate then the
=item B<-id_prefix> I<val>
Generate SSL/TLS session IDs prefixed by I<val>. This is mostly useful
-for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
+for testing any SSL/TLS code (e.g. proxies) that wish to deal with multiple
servers, when each of which might be generating a unique range of session
-IDs (eg. with a certain prefix).
+IDs (e.g. with a certain prefix).
=item B<-verify_return_error>
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using L<openssl-s_client(1)> the CA list can be
-viewed and checked. However some servers only request client authentication
+viewed and checked. However, some servers only request client authentication
after a specific URL is requested. To obtain the list in this case it
is necessary to use the B<-prexit> option of L<openssl-s_client(1)> and
send an HTTP request for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
option it will not be used unless the server specifically requests
-a client certificate. Therefore merely including a client certificate
+a client certificate. Therefore, merely including a client certificate
on the command line is no guarantee that the certificate works.
=head1 BUGS
Since the SSL session output contains the master key it is
possible to read the contents of an encrypted session using this
-information. Therefore appropriate security precautions should be taken if
+information. Therefore, appropriate security precautions should be taken if
the information is being output by a "real" application. This is however
strongly discouraged and should only be used for debugging purposes.
=item B<esc_2254>
Escape the "special" characters in a field as required by RFC 2254 in a field.
-That is, the B<NUL> character and and of C<()*>.
+That is, the B<NUL> character and of C<()*>.
=item B<esc_ctrl>
In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
integer of almost arbitrary size and so cannot always be represented by a C
-B<int64_t> type. However in many cases (for example version numbers) they
+B<int64_t> type. However, in many cases (for example version numbers) they
represent small integers which can be more easily manipulated if converted to
an appropriate C integer type.
is null terminated or does not contain embedded nulls. The actual format
of the data will depend on the actual string type itself: for example
for an IA5String the data will be ASCII, for a BMPString two bytes per
-character in big endian format, and for an UTF8String it will be in UTF8 format.
+character in big endian format, and for a UTF8String it will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format
when calling ASN1_STRING_set().
If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
return value is nonzero. Technically if both parameters are NULL the two
-types could be absent OPTIONAL fields and so should match, however passing
+types could be absent OPTIONAL fields and so should match, however, passing
NULL values could also indicate a programming error (for example an
unparsable type which returns NULL) for types which do B<not> match. So
applications should handle the case of two absent values separately.
be stored in I<*numfds>. It is the caller's responsibility to ensure that
sufficient memory has been allocated in I<*fd> to receive all the file
descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will
-return no file descriptors but will still populate I<*numfds>. Therefore
+return no file descriptors but will still populate I<*numfds>. Therefore,
application code is typically expected to call this function twice: once to get
the number of fds, and then again when sufficient memory has been allocated. If
only one asynchronous engine is being used then normally this call will only
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
+is included, commonly as one of the first included headers. Therefore,
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
+is included, commonly as one of the first included headers. Therefore,
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
to decrypt. Some programs and protocols simplify this, like SSH, where
B<ivec> is simply initialized to zero.
BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
-BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
+BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt a variable
number of bytes (the amount does not have to be an exact multiple of 8). The
purpose of the latter two is to simulate stream ciphers, and therefore, they
need the parameter B<num>, which is a pointer to an integer where the current
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
it back to an uninitialised state.
-BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
+BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of
size B<wherelen> with an address in network byte order pointed at
by B<where> and a port number in network byte order in B<port> (except
for the B<AF_UNIX> protocol family, where B<port> is meaningless and
The BIO_lookup_ex() implementation uses the platform provided getaddrinfo()
function. On Linux it is known that specifying 0 for the protocol will not
-return any SCTP based addresses when calling getaddrinfo(). Therefore if an SCTP
+return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP
address is required then the B<protocol> parameter to BIO_lookup_ex() should be
explicitly set to IPPROTO_SCTP. The same may be true on other platforms.
operation usually pass the operation to the next BIO in the chain.
This often means there is no need to locate the required BIO for
a particular operation, it can be called on a chain and it will
-be automatically passed to the relevant BIO. However this can cause
+be automatically passed to the relevant BIO. However, this can cause
unexpected results: for example no current filter BIOs implement
BIO_seek(), but this may still succeed if the chain ends in a FILE
or file descriptor BIO.
...
BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
- SSL_operations(); /* e.g SSL_read and SSL_write */
+ SSL_operations(); /* e.g. SSL_read and SSL_write */
...
application | TLS-engine
=head1 DESCRIPTION
BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
-callback. The callback is called during most high level BIO operations. It can
+callback. The callback is called during most high-level BIO operations. It can
be used for debugging purposes to trace operations on a BIO or to modify its
operation.
is not considered important.
Chain verification should arguably be performed using the signing time rather
-than the current time. However since the signing time is supplied by the
+than the current time. However, since the signing time is supplied by the
signer it cannot be trusted without additional evidence (such as a trusted
timestamp).
openssl/crypto.h header are dependent on some of the types customarily
made available by including windows.h. The application developer is
likely to require control over when the latter is included, commonly as
-one of the first included headers. Therefore it is defined as an
+one of the first included headers. Therefore, it is defined as an
application developer's responsibility to include windows.h prior to
crypto.h where use of CRYPTO_THREAD_* types and functions is required.
This will replace the DH_METHOD used by the DH key and if the previous method
was supplied by an ENGINE, the handle to that ENGINE will be released during the
change. It is possible to have DH keys that only work with certain DH_METHOD
-implementations (eg. from an ENGINE module that supports embedded
+implementations (e.g. from an ENGINE module that supports embedded
hardware-protected keys), and in such cases attempting to change the DH_METHOD
for the key can have unexpected results.
B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
previous method was supplied by an ENGINE, the handle to that ENGINE will
be released during the change. It is possible to have DSA keys that only
-work with certain DSA_METHOD implementations (eg. from an ENGINE module
+work with certain DSA_METHOD implementations (e.g. from an ENGINE module
that supports embedded hardware-protected keys), and in such cases
attempting to change the DSA_METHOD for the key can have unexpected
results. See L<DSA_meth_new(3)> for information on constructing custom DSA_METHOD
If DTLS is used over UDP (or any datagram based protocol that does not validate
the source IP) then it is susceptible to this type of attack. TLSv1.3 is
designed to operate over a stream-based transport protocol (such as TCP).
-If TCP is being used then there is no need to use SSL_stateless(). However some
+If TCP is being used then there is no need to use SSL_stateless(). However, some
stream-based transport protocols (e.g. QUIC) may not validate the source
address. In this case a TLSv1.3 application would be susceptible to this attack.
ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0,
ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_size, ECDSA_sign, ECDSA_do_sign,
ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
-ECDSA_do_sign_ex - low level elliptic curve digital signature algorithm (ECDSA)
+ECDSA_do_sign_ex - low-level elliptic curve digital signature algorithm (ECDSA)
functions
=head1 SYNOPSIS
EC_GROUP_set_curve() sets the curve parameters I<p>, I<a> and I<b>. For a curve
over Fp I<p> is the prime for the field. For a curve over F2^m I<p> represents
the irreducible polynomial - each bit represents a term in the polynomial.
-Therefore there will either be three or five bits set dependent on whether the
+Therefore, there will either be three or five bits set dependent on whether the
polynomial is a trinomial or a pentanomial.
In either case, I<a> and I<b> represents the coefficients a and b from the
relevant equation introduced above.
Points can also be described in terms of their compressed co-ordinates. For a
point (x, y), for any given value for x such that the point is on the curve
-there will only ever be two possible values for y. Therefore a point can be set
+there will only ever be two possible values for y. Therefore, a point can be set
using the EC_POINT_set_compressed_coordinates() function where B<x> is the x
co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two
possible values for y should be used.
=head2 Reference counting and handles
Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
-treated as handles - ie. not only as pointers, but also as references to
+treated as handles - i.e. not only as pointers, but also as references to
the underlying ENGINE object. Ie. one should obtain a new reference when
making copies of an ENGINE pointer if the copies will be used (and
released) independently.
To obtain a functional reference from an existing structural reference,
call the ENGINE_init() function. This returns zero if the ENGINE was not
-already operational and couldn't be successfully initialised (eg. lack of
+already operational and couldn't be successfully initialised (e.g. lack of
system drivers, no special hardware attached, etc), otherwise it will
return nonzero to indicate that the ENGINE is now operational and will
have allocated a new B<functional> reference to the ENGINE. All functional
implicit structural reference as well).
The second way to get a functional reference is by asking OpenSSL for a
-default implementation for a given task, eg. by ENGINE_get_default_RSA(),
+default implementation for a given task, e.g. by ENGINE_get_default_RSA(),
ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
section, though they are not usually required by application programmers as
they are used automatically when creating and using the relevant
"algorithm" so all implementations implicitly register using the same 'nid'
index.
-When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
+When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g.
when calling RSA_new_method(NULL)), a "get_default" call will be made to the
ENGINE subsystem to process the corresponding state table and return a
functional reference to an initialised ENGINE whose implementation should be
will want to allow the user to specify exactly which ENGINE they want used
if any is to be used at all. Others may prefer to load all support and have
OpenSSL automatically use at run-time any ENGINE that is able to
-successfully initialise - ie. to assume that this corresponds to
+successfully initialise - i.e. to assume that this corresponds to
acceleration hardware attached to the machine or some such thing. There are
probably numerous other ways in which applications may prefer to handle
things, so we will simply illustrate the consequences as they apply to a
driver or config files it needs to load, required network addresses,
smart-card identifiers, passwords to initialise protected devices,
logging information, etc etc. This class of commands typically needs to be
-passed to an ENGINE B<before> attempting to initialise it, ie. before
+passed to an ENGINE B<before> attempting to initialise it, i.e. before
calling ENGINE_init(). The other class of commands consist of settings or
operations that tweak certain behaviour or cause certain operations to take
place, and these commands may work either before or after ENGINE_init(), or
and input parameters of the control commands supported by an ENGINE using a
structural reference. Note that some control commands are defined by OpenSSL
itself and it will intercept and handle these control commands on behalf of the
-ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
+ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command.
openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
implemented by ENGINEs should be numbered from. Any command value lower than
this symbol is considered a "generic" command is handled directly by the
operations via ENGINE_ctrl(), including passing to and/or from the control
commands data of any arbitrary type. These commands are supported in the
discovery mechanisms simply to allow applications to determine if an ENGINE
-supports certain specific commands it might want to use (eg. application "foo"
+supports certain specific commands it might want to use (e.g. application "foo"
might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
and ENGINE could therefore decide whether or not to support this "foo"-specific
extension).
=head1 DESCRIPTION
-The EVP digest routines are a high level interface to message digests,
+The EVP digest routines are a high-level interface to message digests,
and should be used instead of the digest-specific functions.
The B<EVP_MD> type is a structure for digest method implementation.
=head1 NOTES
The B<EVP> interface to message digests should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the digest used and much more flexible.
New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
=head1 DESCRIPTION
-The EVP signature routines are a high level interface to digital signatures.
+The EVP signature routines are a high-level interface to digital signatures.
Input data is digested first before the signing takes place.
EVP_DigestSignInit_ex() sets up signing context I<ctx> to use a digest with the
The I<pkey> algorithm is used to fetch a B<EVP_SIGNATURE> method implicitly, to
be used for the actual signing. See L<provider(7)/Implicit fetch> for
-more information about implict fetches.
+more information about implicit fetches.
The OpenSSL default and legacy providers support fetching digests and can fetch
those digests from any available provider. The OpenSSL fips provider also
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
EVP_DigestSign() is a one shot operation which signs a single block of data
=head1 DESCRIPTION
-The EVP signature routines are a high level interface to digital signatures.
+The EVP signature routines are a high-level interface to digital signatures.
Input data is digested first before the signature verification takes place.
EVP_DigestVerifyInit_ex() sets up verification context B<ctx> to use a digest
The I<pkey> algorithm is used to fetch a B<EVP_SIGNATURE> method implicitly, to
be used for the actual signing. See L<provider(7)/Implicit fetch> for
-more information about implict fetches.
+more information about implicit fetches.
The OpenSSL default and legacy providers support fetching digests and can fetch
those digests from any available provider. The OpenSSL fips provider also
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
EVP_DigestVerify() is a one shot operation which verifies a single block of
=head1 DESCRIPTION
-The EVP encode routines provide a high level interface to base 64 encoding and
+The EVP encode routines provide a high-level interface to base 64 encoding and
decoding. Base 64 encoding converts binary data into a printable form that uses
the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3
bytes of binary data provided 4 bytes of base 64 encoded data will be produced
=head1 DESCRIPTION
-The EVP cipher routines are a high level interface to certain
+The EVP cipher routines are a high-level interface to certain
symmetric ciphers.
The B<EVP_CIPHER> type is a structure for cipher method implementation.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
-Sets the CCM nonce (IV) length. This call can only be made before specifying an
+Sets the CCM nonce (IV) length. This call can only be made before specifying a
nonce value. The nonce length is given by B<15 - L> so it is 7 by default for
AES.
=head1 NOTES
Where possible the B<EVP> interface to symmetric ciphers should be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the cipher used and much more flexible. Additionally, the
B<EVP> interface will ensure the use of platform specific cryptographic
-acceleration such as AES-NI (the low level interfaces do not provide the
+acceleration such as AES-NI (the low-level interfaces do not provide the
guarantee).
PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
=head1 DESCRIPTION
-The EVP KDF routines are a high level interface to Key Derivation Function
+The EVP KDF routines are a high-level interface to Key Derivation Function
algorithms and should be used instead of algorithm-specific functions.
After creating a B<EVP_KDF_CTX> for the required algorithm using
=head1 DESCRIPTION
-The EVP envelope routines are a high level interface to envelope
+The EVP envelope routines are a high-level interface to envelope
decryption. They decrypt a public key encrypted symmetric key and
then decrypt data using it.
=head2 On B<EVP_PKEY_CTX>
The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
-by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
+by the OpenSSL high-level public key API. Contexts B<MUST NOT> be shared between
threads: that is it is not permissible to use the same context simultaneously
in two threads.
shared secret derivation using the algorithm given when the context was created
using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to
fetch a B<EVP_KEYEXCH> method implicitly, see L<provider(7)/Implicit fetch> for
-more information about implict fetches.
+more information about implicit fetches.
EVP_PKEY_derive_set_peer() sets the peer key: this will normally
be a public key.
provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
keypair.
-These functions use an B<EVP_PKEY_CTX> context, which should primarly
+These functions use an B<EVP_PKEY_CTX> context, which should primarily
be created with L<EVP_PKEY_CTX_new_from_name(3)> or
L<EVP_PKEY_CTX_new_id(3)>.
signing using the algorithm given when the context was created
using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to
fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
-for more information about implict fetches.
+for more information about implicit fetches.
The EVP_PKEY_sign() function performs a public key signing operation
using I<ctx>. The data to be signed is specified using the I<tbs> and
signing using the algorithm given when the context was created
using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to
fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
-for more information about implict fetches.
+for more information about implicit fetches.
The EVP_PKEY_verify() function performs a public key verification operation
using I<ctx>. The signature is specified using the I<sig> and
I<ctx> for signing using the algorithm given when the context was created
using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to
fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
-for more information about implict fetches.
+for more information about implicit fetches.
The EVP_PKEY_verify_recover() function recovers signed data
using I<ctx>. The signature is specified using the I<sig> and
=head1 DESCRIPTION
-The EVP RAND routines are a high level interface to random number generators
+The EVP RAND routines are a high-level interface to random number generators
both deterministic and not.
If you just want to generate random bytes then you don't need to use
these functions: just call RAND_bytes() or RAND_priv_bytes().
=item *
-EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
+EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitialised.
The instantiate call will change this to the ready state.
=item *
EVP_RAND_nonce() returns the length of the nonce.
-EVP_RAND_strength() returns the strenght of the random number generator in bits.
+EVP_RAND_strength() returns the strength of the random number generator in bits.
EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
=head1 DESCRIPTION
-The EVP envelope routines are a high level interface to envelope
+The EVP envelope routines are a high-level interface to envelope
encryption. They generate a random key and IV (if required) then
"envelope" it by using public key encryption. Data can then be
encrypted using this key.
=head1 DESCRIPTION
-The EVP signature routines are a high level interface to digital
+The EVP signature routines are a high-level interface to digital
signatures.
EVP_SignInit_ex() sets up signing context I<ctx> to use digest
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
When signing with DSA private keys the random number generator must be seeded.
=head1 DESCRIPTION
-The EVP signature verification routines are a high level interface to digital
+The EVP signature verification routines are a high-level interface to digital
signatures.
EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
+preference to the low-level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
=head1 RETURN VALUES
EVP_set_default_properties() and EVP_default_properties_enable_fips() return 1
-on success, or 0 on failure. An error is placed on the the error stack if a
+on success, or 0 on failure. An error is placed on the error stack if a
failure occurs.
EVP_default_properties_is_fips_enabled() returns 1 if the 'fips=yes' default
As an example, a hash table may be maintained by code that, for
reasons of encapsulation, has only "const" access to the data being
-indexed in the hash table (ie. it is returned as "const" from
+indexed in the hash table (i.e. it is returned as "const" from
elsewhere in their code) - in this case the LHASH prototypes are
appropriate as-is. Conversely, if the caller is responsible for the
life-time of the data in question, then they may well wish to make
There are several reasons why calling the OpenSSL configuration routines is
advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs).
-However very few applications currently support the control interface and so
+However, very few applications currently support the control interface and so
very few can load and use dynamic ENGINEs. Equally in future more sophisticated
ENGINEs will require certain control operations to customize them. If an
application calls OPENSSL_config() it doesn't need to know or care about
=item bit #64+19 denoting availability of ADCX and ADOX instructions;
=item bit #64+21 denoting availability of VPMADD52[LH]UQ instructions,
-a.k.a. AVX512IFMA extension;
+aka AVX512IFMA extension;
=item bit #64+29 denoting availability of SHA extension;
OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000"
-Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
+Disables the KM-XTS-AES and the KIMD-SHAKE function codes:
OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"
a message string describing the nature of the event, terminated by '\n'.
Even when an activity is successful some warnings may be useful and some degree
-of auditing may be required. Therefore the logging facility supports a severity
+of auditing may be required. Therefore, the logging facility supports a severity
level and the callback function has a B<level> parameter indicating such a
level, such that error, warning, info, debug, etc. can be treated differently.
The callback is activated only when the severity level is sufficient according
The callback function may itself do non-trivial tasks like writing to
a log file or remote stream, which in turn may fail.
-Therefore the function should return 1 on success and 0 on failure.
+Therefore, the function should return 1 on success and 0 on failure.
OSSL_CMP_log_open() initializes the CMP-specific logging facility to output
everything to STDOUT. It fails if the integrated tracing is disabled or STDIO
string OSSL_PARAM structure.
A parameter with name B<key>, storage B<buf> and size B<bsize> is created.
-OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
+OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF string
pointer OSSL_PARAM structure.
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
is created.
-OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
+OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string
pointer OSSL_PARAM structure.
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
is created.
B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.
B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
-the B<I<TYPE>> part of
of B<PEM_write_bio_I<TYPE>> functions as well
+the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
as B<i2d_I<TYPE>_bio> functions.
=head1 SEE ALSO
structure.
The B<RSA_PUBKEY> functions also process an RSA public key using
-an RSA structure. However the public key is encoded using a
+an RSA structure. However, the public key is encoded using a
SubjectPublicKeyInfo structure and an error occurs if the public
key is not RSA.
=head1 BUGS
The PEM read routines in some versions of OpenSSL will not correctly reuse
-an existing structure. Therefore the following:
+an existing structure. Therefore, the following:
PEM_read_bio_X509(bp, &x, 0, NULL);
is not considered important.
Chain verification should arguably be performed using the signing time rather
-than the current time. However since the signing time is supplied by the
+than the current time. However, since the signing time is supplied by the
signer it cannot be trusted without additional evidence (such as a trusted
timestamp).
The ownership of the context data remains with the caller, i.e., it is the
caller's responsibility to keep it available as long as it is needed by the
callbacks and free it after use.
-For more information about the the callback data see the NOTES section.
+For more information about the callback data see the NOTES section.
Setting the callbacks or the callback data is allowed only if the DRBG has
not been initialized yet.
it must also indicate an error by returning a buffer length of 0.
See NOTES section for more details.
-The B<cleanup_entropy>() callback is called from the B<drbg> to to clear and
+The B<cleanup_entropy>() callback is called from the B<drbg> to clear and
free the buffer allocated previously by get_entropy().
The values B<out> and B<outlen> are the random buffer's address and length,
as returned by the get_entropy() callback.
=head1 NAME
-RSA_private_encrypt, RSA_public_decrypt - low level signature operations
+RSA_private_encrypt, RSA_public_decrypt - low-level signature operations
=head1 SYNOPSIS
Applications should instead use L<EVP_PKEY_encrypt_init(3)>,
L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
-These functions handle RSA signatures at a low level.
+These functions handle RSA signatures at a low-level.
RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
message digest with an algorithm identifier) using the private key
B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
previous method was supplied by an ENGINE, the handle to that ENGINE will
be released during the change. It is possible to have RSA keys that only
-work with certain RSA_METHOD implementations (eg. from an ENGINE module
+work with certain RSA_METHOD implementations (e.g. from an ENGINE module
that supports embedded hardware-protected keys), and in such cases
attempting to change the RSA_METHOD for the key can have unexpected
results.
not be freed.
SRP_check_known_gN_param() returns the text representation of the group id
-(ie. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
+(i.e. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
This value should not be freed.
SRP_get_default_gN() returns NULL if I<id> is not a valid group size,
The B<groups> argument is a colon separated list of groups. The group can
be either the B<NIST> name (e.g. B<P-256>), some other commonly used name
where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
-(e.g B<prime256v1>). Group names are case sensitive. The list should be
+(e.g
. B<prime256v1>). Group names are case sensitive. The list should be
in order of preference with the most preferred group first.
Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
The B<groups> argument is a curve name or the special value B<auto> which
picks an appropriate curve based on client and server preferences. The
curve can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
-(e.g B<prime256v1>). Curve names are case sensitive.
+(e.g
. B<prime256v1>). Curve names are case sensitive.
=item B<-cipher> I<ciphers>
The B<value> argument is a colon separated list of groups. The group can be
either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
-(e.g B<prime256v1>). Group names are case sensitive. The list should be in
+(e.g
. B<prime256v1>). Group names are case sensitive. The list should be in
order of preference with the most preferred group first.
Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
For all of the functions below that set the supported groups there must be at
least one group in the list. A number of these functions identify groups via a
-unique integer NID value. However support for some groups may be added by
+unique integer NID value. However, support for some groups may be added by
external providers. In this case there will be no NID assigned for the group.
When setting such groups applications should use the "list" form of these
functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list).
/*
* Prefix the session_id with the required prefix. NB: If our
* prefix is too long, clip it - but there will be worse effects
- * anyway, eg. the server could only possibly create 1 session
- * ID (ie. the prefix!) so all future session negotiations will
+ * anyway, e.g. the server could only possibly create 1 session
+ * ID (i.e. the prefix!) so all future session negotiations will
* fail due to conflicts.
*/
memcpy(id, session_id_prefix, strlen(session_id_prefix) < *id_len ?
information needs to be cached locally.
The TLSv1.3 protocol only supports tickets and does not directly support session
-ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
+ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
The session information is cached on the server and the session id is wrapped up
has occurred so that L<SSL_session_reused(3)> will return true.
There are no known security issues with sharing the same PSK between TLSv1.2 (or
-below) and TLSv1.3. However the RFC has this note of caution:
+below) and TLSv1.3. However, the RFC has this note of caution:
"While there is no known way in which the same PSK might produce related output
in both versions, only limited analysis has been done. Implementations can
prevent sessions being stored in the internal cache (though the application can
add them manually using L<SSL_CTX_add_session(3)>). Note:
in any SSL/TLS servers where external caching is configured, any successful
-session lookups in the external cache (ie. for session-resume requests) would
+session lookups in the external cache (i.e. for session-resume requests) would
normally be copied into the local cache before processing continues - this flag
prevents these additions to the internal cache as well.
Sessions are generated within a certain context. When exporting/importing
sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
to re-import a session generated from another context (e.g. another
-application), which might lead to malfunctions. Therefore each application
+application), which might lead to malfunctions. Therefore, each application
must set its own session id context B<sid_ctx> which is used to distinguish
the contexts and is stored in exported sessions. The B<sid_ctx> can be
any kind of binary data with a given length, it is therefore possible
The handshake should be aborted, either because of an error or because of some
policy. Note that in TLSv1.3 a client may send more than one ticket in a single
-handshake. Therefore just because one ticket is unacceptable it does not mean
+handshake. Therefore, just because one ticket is unacceptable it does not mean
that all of them are. For this reason this option should be used with caution.
=item SSL_TICKET_RETURN_IGNORE
In order to benefit from the pipelining capability. You need to have an engine
that provides ciphers that support this. The OpenSSL "dasync" engine provides
-AES128-SHA based ciphers that have this capability. However these are for
+AES128-SHA based ciphers that have this capability. However, these are for
development and test purposes only.
SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
=item SSL_TLSEXT_ERR_ALERT_WARNING
If this value is returned then the servername is not accepted by the server.
-However the handshake will continue and send a warning alert instead. The value
+However, the handshake will continue and send a warning alert instead. The value
of the alert should be stored in the location pointed to by the B<al> parameter
as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support
warning alerts, so if TLSv1.3 has been negotiated then this return value is
=head1 NOTES
There are no known security issues with sharing the same PSK between TLSv1.2 (or
-below) and TLSv1.3. However the RFC has this note of caution:
+below) and TLSv1.3. However, the RFC has this note of caution:
"While there is no known way in which the same PSK might produce related output
in both versions, only limited analysis has been done. Implementations can
from the file descriptor). This function should only be called if the B<SSL>
object is currently waiting for asynchronous work to complete (i.e.
B<SSL_ERROR_WANT_ASYNC> has been received - see L<SSL_get_error(3)>). Typically
-the list will only contain one file descriptor. However if multiple asynchronous
+the list will only contain one file descriptor. However, if multiple asynchronous
capable engines are in use then more than one is possible. The number of file
descriptors returned is stored in I<*numfds> and the file descriptors themselves
are in I<*fds>. The I<fds> parameter may be NULL in which case no file
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
+is included, commonly as one of the first included headers. Therefore,
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
B<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write
to a non-blocking B<BIO> and it was unable to sent all data to the B<BIO>.
-When the B<BIO> is writeable again, the same function can be called again.
+When the B<BIO> is writable again, the same function can be called again.
Note that the retry may again lead to an B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE> condition.
It is safe to call SSL_read() or SSL_read_ex() when more data is available
even when the call that set this error was an SSL_write() or SSL_write_ex().
-However if the call was an SSL_write() or SSL_write_ex(), it should be called
+However, if the call was an SSL_write() or SSL_write_ex(), it should be called
again to continue sending the application data.
For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
additional bytes will be buffered by OpenSSL but will remain unprocessed until
they are needed. As these bytes are still in an unprocessed state SSL_pending()
-will ignore them. Therefore it is possible for no more bytes to be readable from
+will ignore them. Therefore, it is possible for no more bytes to be readable from
the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
to return 0, even though readable application data bytes are available (because
the data is in unprocessed buffered records).
The read functions work based on the SSL/TLS records. The data are received in
records (with a maximum record size of 16kB). Only when a record has been
completely received, can it be processed (decryption and check of integrity).
-Therefore data that was not retrieved at the last read call can still be
+Therefore, data that was not retrieved at the last read call can still be
buffered inside the SSL layer and will be retrieved on the next read
call. If B<num> is higher than the number of bytes buffered then the read
functions will return with the bytes buffered. If no more bytes are in the
server. If a client sends more data than this then the connection will abort.
The configured value for max_early_data on a server may change over time as
-required. However clients may have tickets containing the previously configured
+required. However, clients may have tickets containing the previously configured
max_early_data value. The recv_max_early_data should always be equal to or
higher than any recently configured max_early_data value in order to avoid
aborted connections. The recv_max_early_data should never be set to less than
the possibility of replay attacks.
The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs)
-(e.g. see SSL_CTX_set_psk_find_session_callback(3)). Therefore extreme caution
+(e.g. see SSL_CTX_set_psk_find_session_callback(3)). Therefore, extreme caution
should be applied when combining external PSKs with early data.
Some applications may mitigate the replay risks in other ways. For those
SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects
the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the
rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take
-ownership of one reference. Therefore it may be necessary to increment the
+ownership of one reference. Therefore, it may be necessary to increment the
number of references available using L<BIO_up_ref(3)> before calling the set0
functions.
If the B<rbio> and B<wbio> parameters are different and the B<wbio>
is the same as the
previously set value and the old B<rbio> and B<wbio> values were different
-to each
-other then one reference is consumed for the B<rbio> and one reference
-is consumed
-for the B<wbio>.
+to each other, then one reference is consumed for the B<rbio> and one
+reference is consumed for the B<wbio>.
=back
=head1 DESCRIPTION
-A method contains a few functions that implement the low level of the
+A method contains a few functions that implement the low-level of the
User Interface.
These functions are:
=head1 NOTES
In almost all cases an extension can occur at most once and multiple
-occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
+occurrences is an error. Therefore, the B<idx> parameter is usually B<NULL>.
The B<flags> parameter may be one of the following values.
using X509_STORE_add_cert() or X509_STORE_add_crl(). This increments
its reference count. However, the X509_STORE_CTX_get_by_subject()
function also increases the reference count which leads to one too
-many references being held. Therefore applications should
+many references being held. Therefore, applications should
additionally call X509_free() or X509_CRL_free() to decrement the
reference count again.
the default library context and a NULL property query string are used.
X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure.
-The context can then be reused with an new call to X509_STORE_CTX_init().
+The context can then be reused with a new call to X509_STORE_CTX_init().
X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx>
is no longer valid.
by I<ctx> to be I<chain>.
Ownership of the chain is transferred to I<ctx> and should not be
free'd by the caller.
-X509_STORE_CTX_get0_chain() returns a the internal pointer used by the
+X509_STORE_CTX_get0_chain() returns the internal pointer used by the
I<ctx> that contains the validated chain.
X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
=head1 RETURN VALUES
-X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an
+X509_STORE_CTX_new() returns a newly allocates context or B<NULL> is an
error occurred.
X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred.
verification, either by overriding error conditions or logging errors for
debugging purposes.
-However a verification callback is B<not> essential and the default operation
+However, a verification callback is B<not> essential and the default operation
is often sufficient.
The B<ok> parameter to the callback indicates the value the callback should
domain names must be given in A-label form. The B<namelen> argument
must be the number of characters in the name string or zero in which
case the length is calculated with strlen(B<name>). When B<name> starts
-with a dot (e.g ".example.com"), it will be matched by a certificate
+with a dot (e.g. ".example.com"), it will be matched by a certificate
valid for any sub-domain of B<name>, (see also
B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below).
=over 4
-=item -1 an error condition has occured
+=item -1 an error condition has occurred
=item E<32>1 if the certificate was created to perform the purpose represented by I<id>
=over 4
-=item -1 an error condition has occured
+=item -1 an error condition has occurred
=item E<32>0 not a CA or does not have the purpose represented by I<id>
empty structure such as that returned by TYPE_new().
The encoded data is in binary form and may contain embedded zeros.
-Therefore any FILE pointers or BIOs should be opened in binary mode.
+Therefore, any FILE pointers or BIOs should be opened in binary mode.
Functions such as strlen() will B<not> return the correct length
of the encoded structure.
This is a string extension with one of two legal values. If it is the word
B<hash>, then OpenSSL will follow the process in RFC 5280 to calculate the
hash value.
-Otherwise, the value should be a hex string to output directly, however this
+Otherwise, the value should be a hex string to output directly, however, this
is strongly discouraged.
Example:
The output length of the KRB5KDF derivation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function, and MUST match the key
-length for the chosen cipher or an error is returned. Moreover the
+length for the chosen cipher or an error is returned. Moreover, the
constant's length must not exceed the block size of the cipher.
Since the KRB5KDF output length depends on the chosen cipher, calling
L<EVP_KDF_size(3)> to obtain the requisite length returns the correct length
=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer>
An optional value to set the maximum length of the generated private key.
-The default valure used if this is not set is the maximum value of
+The default value used if this is not set is the maximum value of
BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
Where s is the security strength of the key which has values of
112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
This is only supported by X25519 and X448. The group name must be "x25519" or
-"x448" repsectively for those algorithms. This is only present for consistency
+"x448" respectively for those algorithms. This is only present for consistency
with other key exchange algorithms and is typically not needed.
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
Symmetric encryption is available with the L<B<EVP_Encrypt>I<XXX>|EVP_EncryptInit(3)>
functions. The L<B<EVP_Digest>I<XXX>|EVP_DigestInit(3)> functions provide message digests.
-The B<EVP_PKEY>I<XXX> functions provide a high level interface to
+The B<EVP_PKEY>I<XXX> functions provide a high-level interface to
asymmetric algorithms. To create a new EVP_PKEY see
L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
with a private key of a particular algorithm by using the functions
=item For signing and verifying see L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>.
However, note that
-these functions do not perform a digest of the data to be signed. Therefore
+these functions do not perform a digest of the data to be signed. Therefore,
normally you would use the L<EVP_DigestSignInit(3)>
functions for this purpose.
implementations automatically in preference to built in software
implementations. For more information, consult the engine(3) man page.
-Although low level algorithm specific functions exist for many algorithms
+Although low-level algorithm specific functions exist for many algorithms
their use is discouraged. They cannot be used with an ENGINE and ENGINE
-versions of new algorithms cannot be accessed using the low level functions.
+versions of new algorithms cannot be accessed using the low-level functions.
Also makes code harder to adapt to new algorithms and some options are not
-cleanly supported at the low level and some operations are more efficient
-using the high level interface.
+cleanly supported at the low-level and some operations are more efficient
+using the high-level interface.
=head1 SEE ALSO
B<OSSL_PARAM>s should provide details about the capability with the name given
in the I<capability> argument relevant for the provider context I<provctx>. If a
provider supports multiple capabilities with the given name then it may call the
-callback multipe times (one for each capability). Capabilities can be useful for
+callback multiple times (one for each capability). Capabilities can be useful for
describing the services that a provider can offer. For further details see the
L</CAPABILITIES> section below. It should return 1 on success or 0 on error.
=head1 CAPABILITIES
-Capabilties describe some of the services that a provider can offer.
+Capabilities describe some of the services that a provider can offer.
Applications can query the capabilities to discover those services.
=head3 "TLS-GROUP" Capability
---------------------
When you have gathered corpus data from more than one fuzzer run
-or for any other reason want to to minimize the data
+or for any other reason want to minimize the data
in some corpus subdirectory `fuzz/corpora/DIR` this can be done as follows:
mkdir fuzz/corpora/NEWDIR
# This is from http://man7.org/linux/man-pages/man7/man-pages.7.html
my %preferred_words = (
+ 'a.k.a.' => 'aka',
'bitmask' => 'bit mask',
'builtin' => 'built-in',
#'epoch' => 'Epoch', # handled specially, below
projects / thirdparty / openssl.git / commitdiff
