Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update (add quic)

Browse Source
This commit is contained in:
Hakase
2020-07-12 19:52:18 +09:00
parent 3a6d64bb68
commit e85ee33eee
501 changed files with 19166 additions and 10232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/internal/man3/ossl_cmp_hdr_init.pod
+8 -1
View File
@@ -4,6 +4,7 @@
ossl_cmp_hdr_set_pvno,
ossl_cmp_hdr_get_pvno,
ossl_cmp_hdr_get_protection_nid,
ossl_cmp_hdr_get0_sendernonce,
ossl_cmp_general_name_is_NULL_DN,
ossl_cmp_hdr_set1_sender,
@@ -25,6 +26,7 @@ ossl_cmp_hdr_init
int ossl_cmp_hdr_set_pvno(OSSL_CMP_PKIHEADER *hdr, int pvno);
int ossl_cmp_hdr_get_pvno(const OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_hdr_get_protection_nid(const OSSL_CMP_PKIHEADER *hdr);
ASN1_OCTET_STRING
*ossl_cmp_hdr_get0_sendernonce(const OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_general_name_is_NULL_DN(GENERAL_NAME *name);
@@ -52,6 +54,9 @@ ossl_cmp_hdr_set_pvno() sets hdr->pvno to the given B<pvno>.
ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
ossl_cmp_hdr_get_protection_nid returns the NID of the protection algorithm
in B<hdr> or NID_undef on error.
ossl_cmp_hdr_get0_sendernonce() returns the sender nonce of the given PKIHeader.
ossl_cmp_general_name_is_NULL_DN() determines if the given GENERAL_NAME
@@ -110,7 +115,9 @@ CMP is defined in RFC 4210 (and CRMF in RFC 4211).
ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
ossl_cmp_hdr_get0_sendernonce() returns the respective nonce.
ossl_cmp_hdr_get_protection_nid returns the respective NID, NID_undef on error.
ossl_cmp_hdr_get0_sendernonce() returns the respective nonce, or NULL.
ossl_cmp_general_name_is_NULL_DN() returns 1 given a NULL-DN, else 0.
doc/internal/man3/ossl_cmp_msg_check_received.pod
-86
View File
@@ -1,86 +0,0 @@
=pod
=head1 NAME
ossl_cmp_allow_unprotected_cb_t,
ossl_cmp_msg_check_received
- does all checks on a received CMP message that can be done generically
=head1 SYNOPSIS
#include "cmp_local.h"
typedef int (*ossl_cmp_allow_unprotected_cb_t)(const OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *msg,
int invalid_protection, int arg);
int ossl_cmp_msg_check_received(OSSL_CMP_CTX *ctx, const OSSL_CMP_MSG *msg,
ossl_cmp_allow_unprotected_cb_t cb, int cb_arg);
=head1 DESCRIPTION
ossl_cmp_msg_check_received() checks the given message B<msg>,
which may be a server response or a request by some client.
It is ensured for the B<msg> that
=over 4
=item it has a valid body type,
=item its protection is present and valid (or a callback function B<cb>
is present and indicates that a missing or invalid protection is acceptable),
=item its recipNonce matches any previous senderNonce stored in B<ctx>, and
=item its transaction ID matches any previous transaction ID stored in B<ctx>.
=back
In case no protection is present and B<cb> is not NULL then this callback
function is called with its B<invalid_protection> parameter being 0, while in
case an invalid protection is present the B<invalid_protection> parameter is 1.
The callback is passed also the arguments B<ctx>, B<msg>, and <cb_arg>
(which typically contains the expected message type).
The callback should return 1 on acceptance, 0 on rejection, or -1 on error.
It should not put and error on the error stack since this could be misleading.
If all checks pass then ossl_cmp_msg_check_received()
=over 4
=item learns the senderNonce from the received message,
=item learns the transaction ID if it is not yet in B<ctx>, and
=item adds any extraCerts contained in the <msg> to the list of untrusted
certificates in B<ctx> for future use, such that
they are available already to the certificate confirmation callback and the
peer does not need to send them again (at least not in the same transaction).
For efficiency, the extraCerts are prepended to the list so they get used first.
=back
=head1 RETURN VALUES
ossl_cmp_msg_check_received() returns the message body type (which is >= 0)
on success, -1 on error.
=head1 SEE ALSO
L<OSSL_CMP_validate_msg(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/internal/man3/ossl_cmp_msg_check_update.pod
+95
View File
@@ -0,0 +1,95 @@
=pod
=head1 NAME
ossl_cmp_allow_unprotected_cb_t,
ossl_cmp_msg_check_update
- generic checks on a received CMP message, updating the context
=head1 SYNOPSIS
#include "cmp_local.h"
typedef int (*ossl_cmp_allow_unprotected_cb_t)(const OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *msg,
int invalid_protection, int arg);
int ossl_cmp_msg_check_update(OSSL_CMP_CTX *ctx, const OSSL_CMP_MSG *msg,
ossl_cmp_allow_unprotected_cb_t cb, int cb_arg);
=head1 DESCRIPTION
ossl_cmp_msg_check_update() does all generic checks on the given message B<msg>,
which may be a server response or a request by some client,
and updates the B<ctx> accordingly.
The B<msg> is checked for the following:
=over 4
=item its sender is of appropriate type (currently only B<X509_NAME>)
and matches any expected sender or srvCert subject given in B<ctx>,
=item its protection is present and valid (or a callback function B<cb>
is present and indicates that a missing or invalid protection is acceptable),
=item its CMP protocol version is acceptable, namely B<OSSL_CMP_PVNO>,
=item its body type is valid,
=item its transaction ID matches any transaction ID given in B<ctx>, and
=item its recipNonce matches any senderNonce given in B<ctx>.
=back
In case no protection is present and B<cb> is not NULL then this callback
function is called with its B<invalid_protection> parameter being 0, while in
case an invalid protection is present the B<invalid_protection> parameter is 1.
The callback is passed also the arguments B<ctx>, B<msg>, and <cb_arg>
(which typically contains the expected message type).
The callback should return 1 on acceptance, 0 on rejection, or -1 on error.
It should not put an error on the error stack since this could be misleading.
ossl_cmp_msg_check_update() adds all extraCerts contained in the <msg> to
the list of untrusted certificates in B<ctx> such that they are already usable
for OSSL_CMP_validate_msg(), which is called internally, and for future use.
Thus they are available also to the certificate confirmation callback, and the
peer does not need to send them again (at least not in the same transaction).
Note that it does not help validating the message before storing the extraCerts
because they are not part of the protected portion of the message anyway.
For efficiency, the extraCerts are prepended to the list so they get used first.
If all checks pass then ossl_cmp_msg_check_update()
records in B<ctx> the senderNonce of the received message as the new recipNonce
and learns the transaction ID if none is currently present in B<ctx>.
Moreover, according to RFC 4210 section 5.3.2, if the message protection is
PBM-based then any certificates in the caPubs field are added to the list of
trusted certificates (if set via L<OSSL_CMP_CTX_set0_trustedStore(3)>).
This way these certs are available for validating subsequent messages in the
same context and could apply to any Polling Response (pollRep), error, or PKI
Confirmation (PKIConf) messages following in the same or future transactions.
=head1 RETURN VALUES
ossl_cmp_msg_check_update() returns 1 on success, -1 on error.
=head1 SEE ALSO
L<OSSL_CMP_validate_msg(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/internal/man3/ossl_provider_new.pod
+17 -2
View File
@@ -13,7 +13,8 @@ ossl_provider_name, ossl_provider_dso,
ossl_provider_module_name, ossl_provider_module_path,
ossl_provider_library_context,
ossl_provider_teardown, ossl_provider_gettable_params,
ossl_provider_get_params, ossl_provider_query_operation
ossl_provider_get_params, ossl_provider_query_operation,
ossl_provider_set_operation_bit, ossl_provider_test_operation_bit
- internal provider routines
=head1 SYNOPSIS
@@ -63,6 +64,10 @@ ossl_provider_get_params, ossl_provider_query_operation
int operation_id,
int *no_cache);
int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
int *result);
=head1 DESCRIPTION
I<OSSL_PROVIDER> is a type that holds all the necessary information
@@ -208,6 +213,13 @@ I<query_operation> function, if the provider has one.
It should return an array of I<OSSL_ALGORITHM> for the given
I<operation_id>.
ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
in a bitstring that's internal to I<provider>.
ossl_provider_tests_operation_bit() checks if the bit operation I<bitnum>
is set (1) or not (0) in the internal I<provider> bitstring, and sets
I<*result> to 1 or 0 accorddingly.
=head1 NOTES
Locating a provider module happens as follows:
@@ -270,6 +282,9 @@ otherwise NULL.
ossl_provider_get_params() returns 1 on success, or 0 on error.
If this function isn't available in the provider, 0 is returned.
ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit()
return 1 on success, or 0 on error.
=head1 SEE ALSO
L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
@@ -280,7 +295,7 @@ The functions described here were all added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man1/CA.pl.pod
+2 -2
View File
@@ -113,7 +113,7 @@ written to standard output.
=item B<-signCA>
This option is the same as the B<-signreq> option except it uses the
This option is the same as the B<-sign> option except it uses the
configuration file section B<v3_ca> and so makes the signed request a
valid CA certificate. This is useful when creating intermediate CA from
a root CA. Extra params are passed to L<openssl-ca(1)>.
@@ -165,7 +165,7 @@ the request and finally create a PKCS#12 file containing it.
CA.pl -newca
CA.pl -newreq
CA.pl -signreq
CA.pl -sign
CA.pl -pkcs12 "My Test Certificate"
=head1 ENVIRONMENT
doc/man1/openssl-ciphers.pod.in
+7
View File
@@ -403,6 +403,13 @@ used and only the two suite B compliant cipher suites
(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
permissible.
=item B<CBC>
All cipher suites using encryption algorithm in Cipher Block Chaining (CBC)
mode. These cipher suites are only supported in TLS v1.2 and earlier. Currently
it's an alias for the following cipherstrings: B<SSL_DES>, B<SSL_3DES>, B<SSL_RC2>,
B<SSL_IDEA>, B<SSL_AES128>, B<SSL_AES256>, B<SSL_CAMELLIA128>, B<SSL_CAMELLIA256>, B<SSL_SEED>.
=back
=head1 EQUAL PREFERENCE GROUPS
doc/man1/openssl-cmp.pod.in
+50 -59
View File
@@ -151,7 +151,7 @@ The B<cmp> command is a client implementation for the Certificate
Management Protocol (CMP) as defined in RFC4210.
It can be used to request certificates from a CA server,
update their certificates,
request certificates to be revoked, and perform other CMP requests.
request certificates to be revoked, and perform other types of CMP requests.
=head1 OPTIONS
@@ -206,16 +206,16 @@ Currently implemented commands are:
=back
B<ir> requests initialization of an End Entity into a PKI hierarchy by means of
issuance of a first certificate.
B<ir> requests initialization of an End Entity into a PKI hierarchy
by issuing a first certificate.
B<cr> requests issuance of an additional certificate for an End Entity already
B<cr> requests issuing an additional certificate for an End Entity already
initialized to the PKI hierarchy.
B<p10cr> requests issuance of an additional certificate similarly to B<cr>
B<p10cr> requests issuing an additional certificate similarly to B<cr>
but uses PKCS#10 CSR format.
B<kur> requests (key) update for an existing, given certificate.
B<kur> requests a (key) update for an existing, given certificate.
B<rr> requests revocation of an existing, given certificate.
@@ -268,8 +268,8 @@ This default is used for IR and CR only if no SANs are set.
The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
In case B<-cert> is not set, for instance when using MSG_MAC_ALG,
the subject DN is also used as sender of the PKI message.
The subject DN is also used as fallback sender of outgoing CMP messages
if no B<-cert> and no B<-oldcert> are given.
=item B<-issuer> I<name>
@@ -393,8 +393,9 @@ It must be given for RR, while for KUR it defaults to B<-cert>.
The reference certificate determined in this way, if any, is also used for
deriving default subject DN and Subject Alternative Names for IR, CR, and KUR.
Its issuer, if any, is used as default recipient in the CMP message header
if neither B<-srvcert>, B<-recipient>, nor B<-issuer> is available.
Its subject is used as sender of outgoing messages if B<-cert> is not given.
Its issuer is used as default recipient in CMP message headers
if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given.
=item B<-revreason> I<number>
@@ -428,13 +429,13 @@ Reason numbers defined in RFC 5280 are:
The IP address or DNS hostname and optionally port (defaulting to 80 or 443)
of the CMP server to connect to using HTTP(S) transport.
The optional "http://" or "https://" prefix is ignored.
The optional I<http://> or I<https://> prefix is ignored.
=item B<-proxy> I<[http[s]://]address[:port][/path]>
The HTTP(S) proxy server to use for reaching the CMP server unless B<no_proxy>
applies, see below.
The optional "http://" or "https://" prefix and any trailing path are ignored.
The optional I<http://> or I<https://> prefix and any trailing path are ignored.
Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>
in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>.
@@ -447,7 +448,7 @@ Default is from the environment variable C<no_proxy> if set, else C<NO_PROXY>.
=item B<-path> I<remote_path>
HTTP path at the CMP server (aka CMP alias) to use for POST requests.
Defaults to "/".
Defaults to I</>.
=item B<-msg_timeout> I<seconds>
@@ -473,8 +474,9 @@ Default is 0 (infinite).
When verifying signature-based protection of CMP response messages,
these are the CA certificate(s) to trust while checking certificate chains
during CMP server authentication.
This option gives more flexibility than the B<-srvcert> option because
it does not pin down the expected CMP server by allowing only one certificate.
This option gives more flexibility than the B<-srvcert> option because the
protection certificate is not pinned but may be any certificate
for which a chain to one of the given trusted certificates can be constructed.
Multiple filenames may be given, separated by commas and/or whitespace
(where in the latter case the whole argument must be enclosed in "...").
@@ -482,65 +484,55 @@ Each source may contain multiple certificates.
=item B<-untrusted> I<sources>
Non-trusted intermediate certificate(s) that may be useful
for constructing the TLS client certificate chain (if TLS is enabled) and
for building certificate chains while verifying the CMP server certificate
(when checking signature-based CMP message protection)
and while verifying the newly enrolled certificate.
These may get added to the extraCerts field sent in requests as far as needed.
Non-trusted intermediate CA certificate(s) that may be useful for cert path
construction for the CMP client certificate (to include in the extraCerts field
of outgoing messages), for the TLS client certificate (if TLS is enabled),
when verifying the CMP server certificate (checking signature-based
CMP message protection), and when verifying newly enrolled certificates.
Multiple filenames may be given, separated by commas and/or whitespace.
Each file may contain multiple certificates.
=item B<-srvcert> I<filename>
The specific CMP server certificate to use and directly trust (even if it is
The specific CMP server certificate to expect and directly trust (even if it is
expired) when verifying signature-based protection of CMP response messages.
May be set alternatively to the B<-trusted> option
if the certificate is available and only this one shall be accepted.
May be set alternatively to the B<-trusted> option to pin the accepted server.
If set, the issuer of the certificate is also used as the recipient of the CMP
request and as the expected sender of the CMP response,
overriding any potential B<-recipient> option.
If set, the subject of the certificate is also used
as default value for the recipient of CMP requests
and as default value for the expected sender of incoming CMP messages.
=item B<-recipient> I<name>
This option may be used to explicitly set the Distinguished Name (DN)
of the CMP message recipient, i.e., the CMP server (usually a CA or RA entity).
Distinguished Name (DN) to use in the recipient field of CMP request messages,
i.e., the CMP server (usually a CA or RA entity).
The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
If a CMP server certificate is given with the B<-srvcert> option, its subject
name is taken as the recipient name and the B<-recipient> option is ignored.
If neither of the two are given, the recipient of the PKI message is
determined in the following order: from the B<-issuer> option if present,
the issuer of old cert given with the B<-oldcert> option if present,
the issuer of the client certificate (B<-cert> option) if present.
The recipient field in the header of CMP messagese is mandatory.
If none of the options that enable the derivation of the recipient name are
given, no suitable value for the recipient in the PKIHeader is available.
As a last resort it is set to NULL-DN.
When a response is received, its sender must match the recipient of the request.
The recipient field in the header of a CMP message is mandatory.
If not given explicitly the recipient is determined in the following order:
the subject of the CMP server certificate given with the B<-srvcert> option,
the B<-issuer> option,
the issuer of the certificate given with the B<-oldcert> option,
the issuer of the CMP client certificate (B<-cert> option),
as far as any of those is present, else the NULL-DN as last resort.
=item B<-expect_sender> I<name>
Distinguished Name (DN) of the expected sender of CMP response messages when
MSG_SIG_ALG is used for protection.
This can be used to ensure that only a particular entity is accepted
as the CMP server, and attackers are not able to use arbitrary certificates
of a trusted PKI hierarchy to fraudulently pose as a CMP server.
Note that this option gives slightly more freedom than B<-srvcert>,
which pins down the server to a particular certificate,
while B<-expect_sender> I<name> will continue to match after updates of the
server cert.
Distinguished Name (DN) expected in the sender field of incoming CMP messages.
Defaults to the subject DN of the pinned B<-srvcert>, if any.
The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
If not given, the subject DN of B<-srvcert>, if provided, will be used.
This can be used to make sure that only a particular entity is accepted as
CMP message signer, and attackers are not able to use arbitrary certificates
of a trusted PKI hierarchy to fraudulently pose as a CMP server.
Note that this option gives slightly more freedom than setting the B<-srvcert>,
which pins the server to the holder of a particular certificate, while the
expected sender name will continue to match after updates of the server cert.
=item B<-ignore_keyusage>
@@ -621,8 +613,8 @@ B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
The client's current certificate.
Requires the corresponding key to be given with B<-key>.
The subject of this certificate will be used as the "sender" field
of outgoing CMP messages, while B<-subjectName> may provide a fallback value.
The subject of this certificate will be used as sender of outgoing CMP messages,
while the subject of B<-oldcert> or B<-subjectName> may provide fallback values.
When using signature-based message protection, this "protection certificate"
will be included first in the extraCerts field of outgoing messages.
In Initialization Request (IR) messages this can be used for authenticating
@@ -630,7 +622,6 @@ using an external entity certificate as defined in appendix E.7 of RFC 4210.
For Key Update Request (KUR) messages this is also used as
the certificate to be updated if the B<-oldcert> option is not given.
If the file includes further certs, they are appended to the untrusted certs.
These may get added to the extraCerts field sent in requests as far as needed.
=item B<-key> I<filename>
@@ -740,8 +731,8 @@ when connecting to CMP server.
=item B<-tls_cert> I<filename>
Client's TLS certificate.
If the file includes further certificates,
they are used for constructing the client cert chain provided to the TLS server.
If the file includes further certs they are used (along with B<-untrusted>
certs) for constructing the client cert chain provided to the TLS server.
=item B<-tls_key> I<filename>
@@ -1015,7 +1006,7 @@ the CMP command-line argument B<-proxy>, for example
-proxy http://192.168.1.1:8080
In the Insta Demo CA scenario both clients and the server may use the pre-shared
secret "insta" and the reference value "3078" to authenticate to each other.
secret I<insta> and the reference value I<3078> to authenticate to each other.
Alternatively, CMP messages may be protected in signature-based manner,
where the trust anchor in this case is F<insta.ca.crt>
@@ -1060,7 +1051,7 @@ and/or on the command line.
The following examples at first do not make use of a configuration file.
They assume that a CMP server can be contacted on the local TCP port 80
and accepts requests under the alias "/pkix/".
and accepts requests under the alias I</pkix/>.
For enrolling its very first certificate the client generates a first client key
and sends an initial request message to the local CMP server
doc/man1/openssl-cms.pod.in
+6 -4
View File
@@ -569,7 +569,8 @@ Message-digest of the eContent OCTET STRING within encapContentInfo being signed
=item *
An ESS signing-certificate or ESS signing-certificate-v2 attribute, as defined in Enhanced Security Services (ESS), RFC 2634 and RFC 5035.
An ESS signing-certificate or ESS signing-certificate-v2 attribute, as defined
in Enhanced Security Services (ESS), RFC 2634 and RFC 5035.
An ESS signing-certificate attribute only allows for the use of SHA-1 as a digest algorithm.
An ESS signing-certificate-v2 attribute allows for the use of any digest algorithm.
@@ -577,9 +578,10 @@ An ESS signing-certificate-v2 attribute allows for the use of any digest algorit
The digital signature value computed on the user data and, when present, on the signed attributes.
Note that currently the B<-cades> option applies only to the B<-sign> operation and is ignored during
the B<-verify> operation, i.e. the signing certification is not checked during the verification process.
This feature might be added in a future version.
NOTE that the B<-cades> option applies to the B<-sign> or B<-verify> operations.
With this option, the B<-verify> operation also checks that the signing-certificates
attribute is present, and its value matches the verification trust chain built
during the verification process.
=back
doc/man1/openssl-fipsinstall.pod.in
+26 -22
View File
@@ -25,20 +25,26 @@ B<openssl fipsinstall>
=head1 DESCRIPTION
This command is used to generate a FIPS module configuration file.
This configuration file can be used each time a FIPS module is loaded
in order to pass data to the FIPS module self tests. The FIPS module always
verifies its MAC, but only needs to run the KAT's once,
at installation.
The generated configuration file consists of:
=over 4
=item - A mac of the FIPS module file.
=item - A MAC of the FIPS module file.
=item - A status indicator that indicates if the known answer Self Tests (KAT's)
have successfully run.
=item - A test status indicator.
This indicates if the Known Answer Self Tests (KAT's) have successfully run.
=item - A MAC of the status indicator.
=back
This configuration file can be used each time a FIPS module is loaded
in order to pass data to the FIPS modules self tests. The FIPS module always
verifies the modules MAC, but only needs to run the KATS once during install.
This file is described in L<fips_config(5)>.
=head1 OPTIONS
@@ -50,32 +56,36 @@ Print a usage message.
=item B<-module> I<filename>
Filename of a fips module to perform an integrity check on.
Filename of the FIPS module to perform an integrity check on.
=item B<-out> I<configfilename>
Filename to output the configuration data to, or standard output by default.
Filename to output the configuration data to; the default is standard output.
=item B<-in> I<configfilename>
Input filename to load configuration data from. Used with the '-verify' option.
Standard input is used if the filename is '-'.
Input filename to load configuration data from. Used with the B<-verify> option.
Standard input is used if the filename is C<->.
=item B<-verify>
Verify that the input configuration file contains the correct information
Verify that the input configuration file contains the correct information.
=item B<-provider_name> I<providername>
Name of the provider inside the configuration file.
This must be specified.
=item B<-section_name> I<sectionname>
Name of the section inside the configuration file.
This must be specified.
=item B<-mac_name> I<name>
Specifies the name of a supported MAC algorithm which will be used.
The MAC mechanisms that are available will depend on the options
used when building OpenSSL.
To see the list of supported MAC's use the command
C<openssl list -mac-algorithms>. The default is B<HMAC>.
@@ -122,10 +132,10 @@ Do not output pass/fail messages. Implies B<-noout>.
=item B<-corrupt_desc> I<selftest_description>,
B<-corrupt_type> I<selftest_type>
The corrupt options can be used to test failure of one or more self test(s) by
The corrupt options can be used to test failure of one or more self tests by
name.
Either option or both may be used to select the self test(s) to corrupt.
Refer to the entries for "st-desc" and "st-type" in L<OSSL_PROVIDER-FIPS(7)> for
Either option or both may be used to select the tests to corrupt.
Refer to the entries for B<st-desc> and B<st-type> in L<OSSL_PROVIDER-FIPS(7)> for
values that can be used.
=back
@@ -145,18 +155,12 @@ Verify that the configuration file F<fips.cnf> contains the correct info:
-section_name fips_install -mac_name HMAC -macopt digest:SHA256 \
-macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 -verify
Corrupt any self tests which have the description 'SHA1':
Corrupt any self tests which have the description C<SHA1>:
openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
-section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \
-macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \
-corrupt_desc', 'SHA1'
=head1 NOTES
The MAC mechanisms that are available will depend on the options
used when building OpenSSL.
The command C<openssl list -mac-algorithms> command can be used to list them.
-corrupt_desc 'SHA1'
=head1 SEE ALSO
doc/man1/openssl-genrsa.pod.in
+2 -1
View File
@@ -33,7 +33,7 @@ B<openssl> B<genrsa>
{- $OpenSSL::safe::opt_provider_synopsis -}
[B<numbits>]
=for openssl ifdef engine
=for openssl ifdef engine 3
=head1 DESCRIPTION
@@ -70,6 +70,7 @@ for if it is not supplied via the B<-passout> argument.
=item B<-F4>, B<-f4>, B<-3>
The public exponent to use, either 65537 or 3. The default is 65537.
The B<-3> option has been deprecated.
=item B<-primes> I<num>
doc/man1/openssl-kdf.pod.in
+1 -1
View File
@@ -46,7 +46,7 @@ Output the derived key in binary form. Uses hexadecimal text format if not speci
Passes options to the KDF algorithm.
A comprehensive list of parameters can be found in the EVP_KDF_CTX
implementation documentation.
Common parameter names used by EVP_KDF_CTX_set_params() are:
Common parameter names used by EVP_KDF_set_ctx_params() are:
=over 4
doc/man1/openssl-mac.pod.in
+1 -1
View File
@@ -49,7 +49,7 @@ Output the MAC in binary form. Uses hexadecimal text format if not specified.
Passes options to the MAC algorithm.
A comprehensive list of controls can be found in the EVP_MAC implementation
documentation.
Common parameter names used by EVP_MAC_CTX_get_params() are:
Common parameter names used by EVP_MAC_get_ctx_params() are:
=over 4
doc/man1/openssl-s_client.pod.in
+10
View File
@@ -78,6 +78,7 @@ B<openssl> B<s_client>
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-ignore_unexpected_eof>]
[B<-bugs>]
[B<-comp>]
[B<-no_comp>]
@@ -578,6 +579,15 @@ effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
=item B<-ignore_unexpected_eof>
Some TLS implementations do not send the mandatory close_notify alert on
shutdown. If the application tries to wait for the close_notify alert but the
peer closes the connection without sending it, an error is generated. When this
option is enabled the peer does not need to send the close_notify alert and a
closed connection will be treated as if the close_notify alert was received.
For more information on shutting down a connection, see L<SSL_shutdown(3)>.
=item B<-bugs>
There are several known bugs in SSL and TLS implementations. Adding this
doc/man1/openssl-s_server.pod.in
+10
View File
@@ -47,6 +47,7 @@ B<openssl> B<s_server>
[B<-WWW>]
[B<-http_server_binmode>]
[B<-no_ca_names>]
[B<-ignore_unexpected_eof>]
[B<-servername>]
[B<-servername_fatal>]
[B<-tlsextdebug>]
@@ -420,6 +421,15 @@ Disable TLS Extension CA Names. You may want to disable it for security reasons
or for compatibility with some Windows TLS implementations crashing when this
extension is larger than 1024 bytes.
=item B<-ignore_unexpected_eof>
Some TLS implementations do not send the mandatory close_notify alert on
shutdown. If the application tries to wait for the close_notify alert but the
peer closes the connection without sending it, an error is generated. When this
option is enabled the peer does not need to send the close_notify alert and a
closed connection will be treated as if the close_notify alert was received.
For more information on shutting down a connection, see L<SSL_shutdown(3)>.
=item B<-id_prefix> I<val>
Generate SSL/TLS session IDs prefixed by I<val>. This is mostly useful
doc/man1/openssl.pod
+7 -3
View File
@@ -1298,9 +1298,9 @@ General SSL/TLS.
SSL/TLS cipher.
=item B<ENGINE_CONF>
=item B<CONF>
ENGINE configuration.
Show details about provider and engine configuration.
=item B<ENGINE_TABLE>
@@ -1405,7 +1405,11 @@ The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
is silently ignored.
The B<-xcertform> and B<-xkeyform> options
are obsolete since OpenSSL 3.0.0 and have no effect.
are obsolete since OpenSSL 3.0 and have no effect.
The interactive mode, which could be invoked by running C<openssl>
with no further arguments, was removed in OpenSSL 3.0, and running
that program with no arguments is now equivalent to C<openssl help>.
=head1 COPYRIGHT
doc/man3/ASN1_STRING_TABLE_add.pod
+2 -2
View File
@@ -13,7 +13,7 @@ ASN1_STRING_TABLE_cleanup - ASN1_STRING_TABLE manipulation functions
int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,
unsigned long mask, unsigned long flags);
ASN1_STRING_TABLE * ASN1_STRING_TABLE_get(int nid);
ASN1_STRING_TABLE *ASN1_STRING_TABLE_get(int nid);
void ASN1_STRING_TABLE_cleanup(void);
=head1 DESCRIPTION
@@ -55,7 +55,7 @@ L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/ASN1_STRING_length.pod
+4 -4
View File
@@ -11,10 +11,10 @@ ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
const unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char *ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(const ASN1_STRING *a);
ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a);
int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
@@ -103,7 +103,7 @@ L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/ASN1_STRING_new.pod
+3 -3
View File
@@ -9,8 +9,8 @@ ASN1_STRING allocation functions
#include <openssl/asn1.h>
ASN1_STRING * ASN1_STRING_new(void);
ASN1_STRING * ASN1_STRING_type_new(int type);
ASN1_STRING *ASN1_STRING_new(void);
ASN1_STRING *ASN1_STRING_type_new(int type);
void ASN1_STRING_free(ASN1_STRING *a);
=head1 DESCRIPTION
@@ -42,7 +42,7 @@ L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/BIO_f_ssl.pod
+9 -6
View File
@@ -96,12 +96,15 @@ chain and calling SSL_shutdown() on its internal SSL
pointer.
BIO_do_handshake() attempts to complete an SSL handshake on the
supplied BIO and establish the SSL connection. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried. If an SSL connection has
already been established this call has no effect.
-supplied BIO and establish the SSL connection.
For non-SSL BIOs the connection is done typically at TCP level.
If domain name resolution yields multiple IP addresses all of them are tried
after connect() failures.
The function returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
The call BIO_should_retry() should be used for non-blocking connect BIOs
to determine if the call should be retried.
If a connection has already been established this call has no effect.
=head1 NOTES
doc/man3/BIO_s_connect.pod
+9 -4
View File
@@ -94,11 +94,16 @@ non blocking I/O is set during the connect process.
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
a single call: that is it creates a new connect BIO with B<name>.
BIO_do_connect() attempts to connect the supplied BIO. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
BIO_do_connect() attempts to connect the supplied BIO.
This performs an SSL/TLS handshake as far as supported by the BIO.
For non-SSL BIOs the connection is done typically at TCP level.
If domain name resolution yields multiple IP addresses all of them are tried
after connect() failures.
The function returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
The call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried.
If a connection has already been established this call has no effect.
=head1 NOTES
doc/man3/BIO_set_callback.pod
+1 -1
View File
@@ -48,7 +48,7 @@ out information relating to each BIO operation. If the callback
argument is set it is interpreted as a BIO to send the information
to, otherwise stderr is used.
BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn
BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
doc/man3/BIO_socket_wait.pod
-58
View File
@@ -1,58 +0,0 @@
=pod
=head1 NAME
BIO_socket_wait,
BIO_wait,
BIO_connect_retry
- BIO socket utility functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#ifndef OPENSSL_NO_SOCK
int BIO_socket_wait(int fd, int for_read, time_t max_time);
#endif
int BIO_wait(BIO *bio, time_t max_time, unsigned int milliseconds);
int BIO_connect_retry(BIO *bio, long timeout);
=head1 DESCRIPTION
BIO_socket_wait() waits on the socket B<fd> for reading if B<for_read> is not 0,
else for writing, at most until B<max_time>.
It succeeds immediately if B<max_time> == 0 (which means no timeout given).
BIO_wait() waits at most until B<max_time> on the given B<bio>,
which is typically socket-based,
for reading if B<bio> is supposed to read, else for writing.
It succeeds immediately if B<max_time> == 0 (which means no timeout given).
If sockets are not available it succeeds after waiting at most given
B<milliseconds> in order to help avoiding a tight busy loop at the caller.
BIO_connect_retry() connects via the given B<bio>, retrying BIO_do_connect()
until success or a timeout or error condition is reached.
If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
to wait until the connection is established. A value of 0 enables waiting
indefinitely, while a value < 0 immediately leads to a timeout condition.
=head1 RETURN VALUES
BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
return -1 on error, 0 on timeout, and 1 on success.
=head1 HISTORY
BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/CMS_verify.pod
+7 -3
View File
@@ -66,10 +66,14 @@ from the content. If the content is not of type B<text/plain> then an error is
returned.
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
verified.
verified, unless CMS_CADES flag is also set.
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
verified.
verified, unless CMS_CADES flag is also set.
If B<CMS_CADES> is set, each signer certificate is checked against the
"ESS signing-certificate" extension added in the signed attributes of the
signature.
If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
@@ -122,7 +126,7 @@ L<ERR_get_error(3)>, L<CMS_sign(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/CRYPTO_get_ex_new_index.pod
+5 -5
View File
@@ -23,7 +23,7 @@ CRYPTO_free_ex_data, CRYPTO_new_ex_data
typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
void *from_d, int idx, long argl, void *argp);
void **from_d, int idx, long argl, void *argp);
int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
@@ -140,10 +140,8 @@ dup_func() is called when a structure is being copied. This is only done
for B<SSL>, B<SSL_SESSION>, B<EC_KEY> objects and B<BIO> chains via
BIO_dup_chain(). The B<to> and B<from> parameters
are pointers to the destination and source B<CRYPTO_EX_DATA> structures,
respectively. The B<from_d> parameter needs to be cast to a B<void **pptr>
as the API has currently the wrong signature; that will be changed in a
future version. The B<*pptr> is a pointer to the source exdata.
When the dup_func() returns, the value in B<*pptr> is copied to the
respectively. The B<*from_d> parameter is a pointer to the source exdata.
When the dup_func() returns, the value in B<*from_d> is copied to the
destination ex_data. If the pointer contained in B<*pptr> is not modified
by the dup_func(), then both B<to> and B<from> will point to the same data.
The B<idx>, B<argl> and B<argp> parameters are as described for the other
@@ -165,6 +163,8 @@ dup_func() should return 0 for failure and 1 for success.
=head1 HISTORY
CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.
The signature of the dup_func() callback was changed in OpenSSL 3.0 to use the
type B<void **> for B<from_d>. Previously this parameter was of type B<void *>.
=head1 COPYRIGHT
doc/man3/EC_GFp_simple_method.pod
+17 -5
View File
@@ -8,6 +8,8 @@ EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_me
#include <openssl/ec.h>
Deprecated since OpenSSL 3.0:
const EC_METHOD *EC_GFp_simple_method(void);
const EC_METHOD *EC_GFp_mont_method(void);
const EC_METHOD *EC_GFp_nist_method(void);
@@ -21,6 +23,10 @@ EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_me
=head1 DESCRIPTION
All const EC_METHOD *EC_GF* functions were deprecated in OpenSSL 3.0, since
EC_METHOD is no longer a public concept.
The Elliptic Curve library provides a number of different implementations through a single common interface.
When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an
implementation method must be provided. The functions described here all return a const pointer to an
@@ -39,10 +45,8 @@ The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521
optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
implementations are not available on all platforms.
EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
obj_mac.h header file.
EC_METHOD_get_field_type() was deprecated in OpenSSL 3.0.
Applications should use EC_GROUP_get_field_type() as a replacement (see L<EC_GROUP_copy(3)>).
=head1 RETURN VALUES
@@ -57,9 +61,17 @@ L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
L<d2i_ECPKParameters(3)>,
L<BN_mod_mul_montgomery(3)>
=head1 HISTORY
EC_GFp_simple_method(), EC_GFp_mont_method(void),
EC_GFp_nist_method(), EC_GFp_nistp224_method(),
EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
EC_GF2m_simple_method(), and EC_METHOD_get_field_type()
were deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EC_GROUP_copy.pod
+19 -6
View File
@@ -22,8 +22,6 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator,
const BIGNUM *order, const BIGNUM *cofactor);
const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
@@ -63,6 +61,10 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
unsigned int *k2, unsigned int *k3);
Deprecated since OpenSSL 3.0:
const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
=head1 DESCRIPTION
EC_GROUP_copy() copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
@@ -71,6 +73,7 @@ EC_GROUP_dup() creates a new EC_GROUP object and copies the content from B<src>
EC_GROUP object.
EC_GROUP_method_of() obtains the EC_METHOD of B<group>.
This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.
EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These
parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
@@ -140,8 +143,12 @@ built-in curves within the library provide seed values that can be obtained. It
EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
this seed value, although it will be preserved in any ASN1 based communications.
EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
the value m.
EC_GROUP_get_degree() gets the degree of the field.
For Fp fields this will be the number of bits in p.
For F2^m fields this will be the value m.
EC_GROUP_get_field_type() identifies what type of field the EC_GROUP structure supports,
which will be either F2^m or Fp.
The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid.
For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
@@ -202,6 +209,10 @@ EC_GROUP_get_point_conversion_form() returns the point_conversion_form for B<gro
EC_GROUP_get_degree() returns the degree for B<group> or 0 if the operation is not supported by the underlying group implementation.
EC_GROUP_get_field_type() returns either B<NID_X9_62_prime_field> for prime curves
or B<NID_X9_62_characteristic_two_field> for binary curves;
these values are defined in the obj_mac.h header file.
EC_GROUP_check_named_curve() returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.
EC_GROUP_get0_order() returns an internal pointer to the group order.
@@ -229,11 +240,13 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=head1 HISTORY
The EC_GROUP_check_named_curve() function was added in OpenSSL 3.0.
EC_GROUP_method_of() was deprecated in OpenSSL 3.0.
EC_GROUP_check_named_curve() and EC_GROUP_get_field_type() were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2013-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EC_GROUP_new.pod
+9 -9
View File
@@ -4,7 +4,6 @@
EC_GROUP_get_ecparameters,
EC_GROUP_get_ecpkparameters,
EC_GROUP_new_ex,
EC_GROUP_new,
EC_GROUP_new_from_ecparameters,
EC_GROUP_new_from_ecpkparameters,
@@ -27,8 +26,6 @@ objects
#include <openssl/ec.h>
EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth);
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
void EC_GROUP_free(EC_GROUP *group);
@@ -62,6 +59,7 @@ Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
void EC_GROUP_clear_free(EC_GROUP *group);
=head1 DESCRIPTION
@@ -83,20 +81,20 @@ Operations in a binary field are performed relative to an
B<irreducible polynomial>. All such curves with OpenSSL use a trinomial or a
pentanomial for this parameter.
A new curve can be constructed by calling EC_GROUP_new_ex(), using the
Although deprecated since OpenSSL 3.0 and should no longer be used,
a new curve can be constructed by calling EC_GROUP_new(), using the
implementation provided by B<meth> (see L<EC_GFp_simple_method(3)>) and
associated with the library context B<ctx> (see L<OPENSSL_CTX(3)>).
The B<ctx> parameter may be NULL in which case the default library context is
used.
It is then necessary to call EC_GROUP_set_curve() to set the curve parameters.
Applications should instead use one of the other EC_GROUP_new_* constructors.
EC_GROUP_new_from_ecparameters() will create a group from the
specified B<params> and
EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK
B<params>.
EC_GROUP_new() is the same as EC_GROUP_new_ex() except that the library context
used is always the default library context.
EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve
over Fp B<p> is the prime for the field. For a curve over F2^m B<p> represents
the irreducible polynomial - each bit represents a term in the polynomial.
@@ -182,7 +180,9 @@ L<OPENSSL_CTX(3)>
=item *
EC_GROUP_new_ex() and EC_GROUP_new_by_curve_name_ex() were added in OpenSSL 3.0.
EC_GROUP_new() was deprecated in OpenSSL 3.0.
EC_GROUP_new_by_curve_name_ex() was added in OpenSSL 3.0.
=item *
@@ -193,7 +193,7 @@ instead.
=head1 COPYRIGHT
Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EC_KEY_new.pod
+13 -3
View File
@@ -40,7 +40,6 @@ EC_KEY objects
point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
int EC_KEY_generate_key(EC_KEY *key);
int EC_KEY_check_key(const EC_KEY *key);
int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);
@@ -56,6 +55,10 @@ EC_KEY objects
size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);
Deprecated since OpenSSL 3.0:
int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
=head1 DESCRIPTION
An EC_KEY represents a public key and, optionally, the associated private
@@ -136,11 +139,14 @@ EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object
(if set). Refer to L<EC_GROUP_copy(3)> for further information on the
asn1_flag.
Although deprecated in OpenSSL 3.0 and should no longer be used,
EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator
for faster point multiplication. See also L<EC_POINT_add(3)>.
Modern versions should instead switch to named curves which OpenSSL has
hardcoded lookup tables for.
EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions
EC_POINT_oct2point() and EC_KEY_point2buf() except they use the public key
EC_POINT_oct2point() and EC_POINT_point2buf() except they use the public key
EC_POINT in B<eckey>.
EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key
@@ -195,9 +201,13 @@ L<EC_GFp_simple_method(3)>,
L<d2i_ECPKParameters(3)>,
L<OPENSSL_CTX(3)>
=head1 HISTORY
EC_KEY_precompute_mult() was deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EC_POINT_add.pod
+16 -12
View File
@@ -15,18 +15,18 @@ EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_i
int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
Deprecated since OpenSSL 3.0:
int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
int EC_POINTs_make_affine(const EC_GROUP *group, size_t num,
EC_POINT *points[], BN_CTX *ctx);
int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
Deprecated since OpenSSL 3.0:
int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,
const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
=head1 DESCRIPTION
@@ -43,7 +43,8 @@ EC_POINT_cmp compares the two supplied points and tests whether or not they are
The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
forced.
forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used.
Modern versions automatically perform this conversion when needed.
EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>.
The value B<n> may be NULL in which case the result is just B<q> * B<m> (variable point multiplication). Alternatively, both B<q> and B<m> may be NULL, and B<n> non-NULL, in which case the result is just generator * B<n> (fixed point multiplication).
@@ -56,8 +57,9 @@ Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_
The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information
about the generator.
about the generator. Precomputation functionality was deprecated in OpenSSL 3.0.
Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should
switch to named curves which OpenSSL has hardcoded lookup tables for.
=head1 RETURN VALUES
@@ -80,11 +82,13 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=head1 HISTORY
EC_POINTs_mul() was deprecated in OpenSSL 3.0.
EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(),
EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult()
were deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EC_POINT_new.pod
+4 -1
View File
@@ -38,7 +38,6 @@ EC_POINT_hex2point
void EC_POINT_clear_free(EC_POINT *point);
int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, const BIGNUM *y,
@@ -68,6 +67,7 @@ EC_POINT_hex2point
Deprecated since OpenSSL 3.0:
const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
EC_POINT *p,
const BIGNUM *x, const BIGNUM *y,
@@ -116,6 +116,8 @@ EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from
B<src> to the newly created B<EC_POINT> object.
EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>.
This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a
public concept.
A valid point on a curve is the special point at infinity. A point is set to
be at infinity by calling EC_POINT_set_to_infinity().
@@ -249,6 +251,7 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=head1 HISTORY
EC_POINT_method_of(),
EC_POINT_set_Jprojective_coordinates_GFp(),
EC_POINT_get_Jprojective_coordinates_GFp(),
EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(),
doc/man3/EVP_EncryptInit.pod
+1 -1
View File
@@ -770,7 +770,7 @@ with a 128-bit key:
/* Don't set key or IV right away; we want to check lengths */
ctx = EVP_CIPHER_CTX_new();
EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
do_encrypt);
OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
doc/man3/EVP_KDF.pod
+25 -29
View File
@@ -3,11 +3,11 @@
=head1 NAME
EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref,
EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup,
EVP_KDF_CTX, EVP_KDF_new_ctx, EVP_KDF_free_ctx, EVP_KDF_dup_ctx,
EVP_KDF_reset, EVP_KDF_derive,
EVP_KDF_size, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
EVP_KDF_size, EVP_KDF_provider, EVP_KDF_get_ctx_kdf, EVP_KDF_is_a,
EVP_KDF_number, EVP_KDF_names_do_all,
EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
EVP_KDF_get_ctx_params, EVP_KDF_set_ctx_params, EVP_KDF_do_all_provided,
EVP_KDF_get_params, EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params,
EVP_KDF_gettable_params - EVP KDF routines
@@ -18,10 +18,10 @@ EVP_KDF_gettable_params - EVP KDF routines
typedef struct evp_kdf_st EVP_KDF;
typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
EVP_KDF_CTX *EVP_KDF_new_ctx(const EVP_KDF *kdf);
const EVP_KDF *EVP_KDF_get_ctx_kdf(EVP_KDF_CTX *ctx);
void EVP_KDF_free_ctx(EVP_KDF_CTX *ctx);
EVP_KDF_CTX *EVP_KDF_dup_ctx(const EVP_KDF_CTX *src);
void EVP_KDF_reset(EVP_KDF_CTX *ctx);
size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
@@ -39,8 +39,8 @@ EVP_KDF_gettable_params - EVP KDF routines
void (*fn)(const char *name, void *data),
void *data);
int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
int EVP_KDF_get_ctx_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
int EVP_KDF_set_ctx_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);
@@ -52,8 +52,8 @@ 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
EVP_KDF_CTX_new(), inputs to the algorithm are supplied
using calls to EVP_KDF_CTX_set_params() before
EVP_KDF_new_ctx(), inputs to the algorithm are supplied
using calls to EVP_KDF_set_ctx_params() before
calling EVP_KDF_derive() to derive the key.
=head2 Types
@@ -68,6 +68,9 @@ EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
algorithms supported by the default provider.
The returned value must eventually be freed with
L<EVP_KDF_free(3)>.
@@ -79,12 +82,12 @@ NULL is a valid parameter, for which this function is a no-op.
=head2 Context manipulation functions
EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
EVP_KDF_new_ctx() creates a new context for the KDF implementation I<kdf>.
EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
EVP_KDF_free_ctx() frees up the context I<ctx>. If I<ctx> is NULL, nothing
is done.
EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
EVP_KDF_get_ctx_kdf() returns the B<EVP_KDF> associated with the context
I<ctx>.
=head2 Computing functions
@@ -104,14 +107,14 @@ parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_KDF_CTX_get_params() retrieves chosen parameters, given the
EVP_KDF_get_ctx_params() retrieves chosen parameters, given the
context I<ctx> and its underlying context.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
EVP_KDF_set_ctx_params() passes chosen parameters to the underlying
context, given a context I<ctx>.
The set of parameters given with I<params> determine exactly what
parameters are passed down.
@@ -123,8 +126,8 @@ defined by the implementation.
EVP_KDF_gettable_params(), EVP_KDF_gettable_ctx_params() and
EVP_KDF_settable_ctx_params() get a constant B<OSSL_PARAM> array that
describes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params()
and EVP_KDF_CTX_set_params(), respectively.
can be used with EVP_KDF_get_params(), EVP_KDF_get_ctx_params()
and EVP_KDF_set_ctx_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head2 Information functions
@@ -234,10 +237,10 @@ NULL on error.
EVP_KDF_up_ref() returns 1 on success, 0 on error.
EVP_KDF_CTX_new() returns either the newly allocated
EVP_KDF_new_ctx() returns either the newly allocated
B<EVP_KDF_CTX> structure or NULL if an error occurred.
EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
EVP_KDF_free_ctx() and EVP_KDF_reset() do not return a value.
EVP_KDF_size() returns the output size. B<SIZE_MAX> is returned to indicate
that the algorithm produces a variable amount of output; 0 to indicate failure.
@@ -248,14 +251,7 @@ supported by the KDF algorithm.
=head1 SEE ALSO
L<EVP_KDF-SCRYPT(7)>
L<EVP_KDF-TLS1_PRF(7)>
L<EVP_KDF-PBKDF2(7)>
L<EVP_KDF-HKDF(7)>
L<EVP_KDF-SS(7)>
L<EVP_KDF-SSHKDF(7)>
L<EVP_KDF-X963(7)>
L<EVP_KDF-X942(7)>
L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>
=head1 HISTORY
@@ -263,7 +259,7 @@ This functionality was added to OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EVP_MAC.pod
+26 -23
View File
@@ -5,8 +5,8 @@
EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
EVP_MAC_is_a, EVP_MAC_number, EVP_MAC_names_do_all,
EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
EVP_MAC_CTX, EVP_MAC_new_ctx, EVP_MAC_free_ctx, EVP_MAC_dup_ctx,
EVP_MAC_get_ctx_mac, EVP_MAC_get_ctx_params, EVP_MAC_set_ctx_params,
EVP_MAC_size, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final,
EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params,
EVP_MAC_do_all_provided - EVP MAC routines
@@ -30,12 +30,12 @@ EVP_MAC_do_all_provided - EVP MAC routines
const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);
void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
EVP_MAC_CTX *EVP_MAC_new_ctx(EVP_MAC *mac);
void EVP_MAC_free_ctx(EVP_MAC_CTX *ctx);
EVP_MAC_CTX *EVP_MAC_dup_ctx(const EVP_MAC_CTX *src);
EVP_MAC *EVP_MAC_get_ctx_mac(EVP_MAC_CTX *ctx);
int EVP_MAC_get_ctx_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
int EVP_MAC_set_ctx_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
int EVP_MAC_init(EVP_MAC_CTX *ctx);
@@ -82,6 +82,9 @@ EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list
of algorithms supported by the default provider.
The returned value must eventually be freed with
L<EVP_MAC_free(3)>.
@@ -93,18 +96,18 @@ NULL is a valid parameter, for which this function is a no-op.
=head2 Context manipulation functions
EVP_MAC_CTX_new() creates a new context for the MAC type I<mac>.
EVP_MAC_new_ctx() creates a new context for the MAC type I<mac>.
The created context can then be used with most other functions
described here.
EVP_MAC_CTX_free() frees the contents of the context, including an
EVP_MAC_free_ctx() frees the contents of the context, including an
underlying context if there is one, as well as the context itself.
NULL is a valid parameter, for which this function is a no-op.
EVP_MAC_CTX_dup() duplicates the I<src> context and returns a newly allocated
EVP_MAC_dup_ctx() duplicates the I<src> context and returns a newly allocated
context.
EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
EVP_MAC_get_ctx_mac() returns the B<EVP_MAC> associated with the context
I<ctx>.
=head2 Computing functions
@@ -133,14 +136,14 @@ parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_MAC_CTX_get_params() retrieves chosen parameters, given the
EVP_MAC_get_ctx_params() retrieves chosen parameters, given the
context I<ctx> and its underlying context.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
EVP_MAC_set_ctx_params() passes chosen parameters to the underlying
context, given a context I<ctx>.
The set of parameters given with I<params> determine exactly what
parameters are passed down.
@@ -152,8 +155,8 @@ defined by the implementation.
EVP_MAC_gettable_params(), EVP_MAC_gettable_ctx_params() and
EVP_MAC_settable_ctx_params() get a constant B<OSSL_PARAM> array that
describes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_MAC_get_params(), EVP_MAC_CTX_get_params()
and EVP_MAC_CTX_set_params(), respectively.
can be used with EVP_MAC_get_params(), EVP_MAC_get_ctx_params()
and EVP_MAC_set_ctx_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head2 Information functions
@@ -267,12 +270,12 @@ the given name, otherwise 0.
EVP_MAC_provider() returns a pointer to the provider for the MAC, or
NULL on error.
EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
EVP_MAC_new_ctx() and EVP_MAC_dup_ctx() return a pointer to a newly
created EVP_MAC_CTX, or NULL if allocation failed.
EVP_MAC_CTX_free() returns nothing at all.
EVP_MAC_free_ctx() returns nothing at all.
EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
EVP_MAC_get_ctx_params() and EVP_MAC_set_ctx_params() return 1 on
success, 0 on error.
EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
@@ -324,8 +327,8 @@ EVP_MAC_do_all_provided() returns nothing at all.
if (mac == NULL
|| key == NULL
|| (ctx = EVP_MAC_CTX_new(mac)) == NULL
|| EVP_MAC_CTX_set_params(ctx, params) <= 0)
|| (ctx = EVP_MAC_new_ctx(mac)) == NULL
|| EVP_MAC_set_ctx_params(ctx, params) <= 0)
goto err;
if (!EVP_MAC_init(ctx))
@@ -344,12 +347,12 @@ EVP_MAC_do_all_provided() returns nothing at all.
printf("%02X", buf[i]);
printf("\n");
EVP_MAC_CTX_free(ctx);
EVP_MAC_free_ctx(ctx);
EVP_MAC_free(mac);
exit(0);
err:
EVP_MAC_CTX_free(ctx);
EVP_MAC_free_ctx(ctx);
EVP_MAC_free(mac);
fprintf(stderr, "Something went wrong\n");
ERR_print_errors_fp(stderr);
doc/man3/EVP_PKEY_ASN1_METHOD.pod
+4 -4
View File
@@ -43,7 +43,7 @@ EVP_PKEY_get0_asn1
void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
int (*pub_decode) (EVP_PKEY *pk,
X509_PUBKEY *pub),
const X509_PUBKEY *pub),
int (*pub_encode) (X509_PUBKEY *pub,
const EVP_PKEY *pk),
int (*pub_cmp) (const EVP_PKEY *a,
@@ -170,7 +170,7 @@ They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
The pub_cmp() method is called when two public keys are to be
compared.
It MUST return 1 when the keys are equal, 0 otherwise.
It's called by L<EVP_PKEY_cmp(3)>.
It's called by L<EVP_PKEY_eq(3)>.
The pub_print() method is called to print a public key in humanly
readable text to B<out>, indented B<indent> spaces.
@@ -228,7 +228,7 @@ It's called by L<EVP_PKEY_copy_parameters(3)>.
The param_cmp() method compares the parameters of keys B<a> and B<b>.
It MUST return 1 when the keys are equal, 0 when not equal, or a
negative number on error.
It's called by L<EVP_PKEY_cmp_parameters(3)>.
It's called by L<EVP_PKEY_parameters_eq(3)>.
The param_print() method prints the private key parameters in humanly
readable text to B<out>, indented B<indent> spaces.
@@ -434,7 +434,7 @@ B<EVP_PKEY_ASN1_METHOD> object otherwise.
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EVP_PKEY_CTX_ctrl.pod
+1 -57
View File
@@ -2,10 +2,6 @@
=head1 NAME
EVP_PKEY_CTX_get_params,
EVP_PKEY_CTX_gettable_params,
EVP_PKEY_CTX_set_params,
EVP_PKEY_CTX_settable_params,
EVP_PKEY_CTX_ctrl,
EVP_PKEY_CTX_ctrl_str,
EVP_PKEY_CTX_ctrl_uint64,
@@ -78,11 +74,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/evp.h>
int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
int cmd, int p1, void *p2);
int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
@@ -186,49 +177,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
=head1 DESCRIPTION
The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and
send arbitrary parameters from and to the algorithm implementation respectively.
Not all parameters may be supported by all providers.
See L<OSSL_PROVIDER(3)> for more information on providers.
See L<OSSL_PARAM(3)> for more information on parameters.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation.
The parameters currently supported by the default provider are:
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
Sets the DH padding mode.
If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeros
up to the size of the DH prime I<p>.
If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
performed.
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
Gets and sets the name of the digest algorithm used for the input to the
signature functions.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
Gets and sets the output size of the digest algorithm used for the input to the
signature functions.
The length of the "digest-size" parameter should not exceed that of a B<size_t>.
The internal algorithm that supports this parameter is DSA.
=back
EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
constant B<OSSL_PARAM> array that describes the gettable and
settable parameters for the current algorithm implementation, i.e. parameters
that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation.
The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
I<ctx>. The key type used must match I<keytype> if it is not -1. The parameter
I<optype> is a mask indicating which operations the control can be applied to.
@@ -662,17 +610,13 @@ allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id
=head1 RETURN VALUES
EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
error.
It may also return NULL if there are no settable parameters available.
All other functions and macros described on this page return a positive value
for success and 0 or a negative value for failure. In particular a return value
of -2 indicates the operation is not supported by the public key algorithm.
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_params(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)>,
doc/man3/EVP_PKEY_CTX_new.pod
+2 -1
View File
@@ -16,7 +16,8 @@ EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free
const char *name,
const char *propquery);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OPENSSL_CTX *libctx,
EVP_PKEY *pkey);
EVP_PKEY *pkey,
const char *propquery);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
doc/man3/EVP_PKEY_CTX_set_params.pod
+95
View File
@@ -0,0 +1,95 @@
=pod
=head1 NAME
EVP_PKEY_CTX_set_params,
EVP_PKEY_CTX_settable_params,
EVP_PKEY_CTX_get_params,
EVP_PKEY_CTX_gettable_params
- provider parameter passing operations
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
=head1 DESCRIPTION
The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions allow
transfer of arbitrary key parameters to and from providers.
Not all parameters may be supported by all providers.
See L<OSSL_PROVIDER(3)> for more information on providers.
See L<OSSL_PARAM(3)> for more information on parameters.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation.
These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now
calls these methods internally to interact with providers).
EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a
constant B<OSSL_PARAM> array that describes the gettable and
settable parameters for the current algorithm implementation, i.e. parameters
that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation.
=head2 Parameters
Examples of EVP_PKEY parameters include the following:
L<provider-keymgmt(7)/Common parameters>
L<provider-keyexch(7)/Key Exchange parameters>
L<provider-signature(7)/Signature parameters>
L<EVP_PKEY-RSA(7)/Common RSA parameters>
L<EVP_PKEY-RSA(7)/RSA key generation parameters>
L<EVP_PKEY-FFC(7)/FFC parameters>
L<EVP_PKEY-FFC(7)/FFC key generation parameters>
L<EVP_PKEY-DSA(7)/DSA parameters>
L<EVP_PKEY-DSA(7)/DSA key generation parameters>
L<EVP_PKEY-DH(7)/DH parameters>
L<EVP_PKEY-DH(7)/DH key generation parameters>
L<EVP_PKEY-EC(7)/Common EC parameters>
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
=head1 RETURN VALUES
EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
error.
It may also return NULL if there are no settable parameters available.
All other functions and macros described on this page return a positive value
for success and 0 or a negative value for failure. In particular a return value
of -2 indicates the operation is not supported by the public key algorithm.
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)>,
L<EVP_PKEY_keygen(3)>
=head1 HISTORY
All functions were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/EVP_PKEY_cmp.pod → doc/man3/EVP_PKEY_copy_parameters.pod
+20 -9
View File
@@ -2,7 +2,8 @@
=head1 NAME
EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters,
EVP_PKEY_missing_parameters, EVP_PKEY_copy_parameters, EVP_PKEY_parameters_eq,
EVP_PKEY_cmp_parameters, EVP_PKEY_eq,
EVP_PKEY_cmp - public key parameter and comparison functions
=head1 SYNOPSIS
@@ -12,7 +13,9 @@ EVP_PKEY_cmp - public key parameter and comparison functions
int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);
int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);
int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b);
int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b);
int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b);
int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b);
=head1 DESCRIPTION
@@ -26,11 +29,11 @@ B<from> to key B<to>. An error is returned if the parameters are missing in
B<from> or present in both B<from> and B<to> and mismatch. If the parameters
in B<from> and B<to> are both present and match this function has no effect.
The function EVP_PKEY_cmp_parameters() compares the parameters of keys
B<a> and B<b>.
The function EVP_PKEY_parameters_eq() checks the parameters of keys
B<a> and B<b> for equality.
The function EVP_PKEY_cmp() compares the public key components and parameters
(if present) of keys B<a> and B<b>.
The function EVP_PKEY_eq() checks the public key components and parameters
(if present) of keys B<a> and B<b> for equality.
=head1 NOTES
@@ -40,7 +43,7 @@ parameters are sometimes omitted from a public key if they are inherited from
the CA that signed it.
Since OpenSSL private keys contain public key components too the function
EVP_PKEY_cmp() can also be used to determine if a private key matches
EVP_PKEY_eq() can also be used to determine if a private key matches
a public key.
=head1 RETURN VALUES
@@ -52,8 +55,8 @@ doesn't use parameters.
These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for
failure.
The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the
keys match, 0 if they don't match, -1 if the key types are different and
The function EVP_PKEY_parameters_eq() and EVP_PKEY_eq() return 1 if their
inputs match, 0 if they don't match, -1 if the key types are different and
-2 if the operation is not supported.
=head1 SEE ALSO
@@ -61,9 +64,17 @@ keys match, 0 if they don't match, -1 if the key types are different and
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_keygen(3)>
=head1 HISTORY
The function EVP_PKEY_cmp was deprecated and renamed to B<EVP_PKEY_eq> and
EVP_PKEY_cmp_parameters was deprecated and renamed to B<EVP_PKEY_parameters_eq>
(without changing semantics) in OpenSSL 3.0.
This was done to avoid confusion on their return values with other _cmp()
functions that return 0 in case their arguments are equal.
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EVP_PKEY_new.pod
+2 -1
View File
@@ -96,7 +96,8 @@ B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key()
except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the
raw private key data, it also takes a cipher algorithm to be used during
creation of a CMAC in the B<cipher> argument.
creation of a CMAC in the B<cipher> argument. The cipher should be a standard
encryption only cipher. For example AEAD and XTS ciphers should not be used.
EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
New applications should use EVP_PKEY_new_raw_private_key() instead.
doc/man3/EVP_md2.pod
+2 -1
View File
@@ -14,7 +14,7 @@ EVP_md2
=head1 DESCRIPTION
MD2 is a cryptographic hash function standardized in RFC 1319 and designed by
Ronald Rivest.
Ronald Rivest. This implementation is only available with the legacy provider.
=over 4
@@ -38,6 +38,7 @@ IETF RFC 1319.
=head1 SEE ALSO
L<evp(7)>,
L<provider(7)>,
L<EVP_DigestInit(3)>
=head1 COPYRIGHT
doc/man3/EVP_md4.pod
+3 -1
View File
@@ -14,7 +14,8 @@ EVP_md4
=head1 DESCRIPTION
MD4 is a cryptographic hash function standardized in RFC 1320 and designed by
Ronald Rivest, first published in 1990.
Ronald Rivest, first published in 1990. This implementation is only available
with the legacy provider.
=over 4
@@ -38,6 +39,7 @@ IETF RFC 1320.
=head1 SEE ALSO
L<evp(7)>,
L<provider(7)>,
L<EVP_DigestInit(3)>
=head1 COPYRIGHT
doc/man3/EVP_mdc2.pod
+3 -1
View File
@@ -14,7 +14,8 @@ EVP_mdc2
=head1 DESCRIPTION
MDC-2 (Modification Detection Code 2 or Meyer-Schilling) is a cryptographic
hash function based on a block cipher.
hash function based on a block cipher. This implementation is only available
with the legacy provider.
=over 4
@@ -38,6 +39,7 @@ ISO/IEC 10118-2:2000 Hash-Function 2, with DES as the underlying block cipher.
=head1 SEE ALSO
L<evp(7)>,
L<provider(7)>,
L<EVP_DigestInit(3)>
=head1 COPYRIGHT
doc/man3/EVP_ripemd160.pod
+2
View File
@@ -15,6 +15,7 @@ EVP_ripemd160
RIPEMD-160 is a cryptographic hash function first published in 1996 belonging
to the RIPEMD family (RACE Integrity Primitives Evaluation Message Digest).
This implementation is only available with the legacy provider.
=over 4
@@ -37,6 +38,7 @@ ISO/IEC 10118-3:2016 Dedicated Hash-Function 1 (RIPEMD-160).
=head1 SEE ALSO
L<evp(7)>,
L<provider(7)>,
L<EVP_DigestInit(3)>
=head1 COPYRIGHT
doc/man3/EVP_whirlpool.pod
+3 -1
View File
@@ -14,7 +14,8 @@ EVP_whirlpool
=head1 DESCRIPTION
WHIRLPOOL is a cryptographic hash function standardized in ISO/IEC 10118-3:2004
designed by Vincent Rijmen and Paulo S. L. M. Barreto.
designed by Vincent Rijmen and Paulo S. L. M. Barreto. This implementation is
only available with the legacy provider.
=over 4
@@ -39,6 +40,7 @@ ISO/IEC 10118-3:2004.
=head1 SEE ALSO
L<evp(7)>,
L<provider(7)>,
L<EVP_DigestInit(3)>
=head1 COPYRIGHT
doc/man3/HMAC.pod
+1 -1
View File
@@ -54,7 +54,7 @@ L<openssl_user_macros(7)>:
=head1 DESCRIPTION
All of the functions described on this page are deprecated. Applications should
instead use L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
instead use L<EVP_MAC_new_ctx(3)>, L<EVP_MAC_free_ctx(3)>, L<EVP_MAC_init(3)>,
L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)>.
HMAC is a MAC (message authentication code), i.e. a keyed hash
doc/man3/ISSUER_SIGN_TOOL_new.pod
-51
View File
@@ -1,51 +0,0 @@
=pod
=head1 NAME
ISSUER_SIGN_TOOL_new, ISSUER_SIGN_TOOL_free,ISSUER_SIGN_TOOL_it,
d2i_ISSUER_SIGN_TOOL, i2d_ISSUER_SIGN_TOOL
=head1 SYNOPSIS
=for openssl generic
#include <openssl/x509v3.h>
extern const ISSUER_SIGN_TOOL_it;
ISSUER_SIGN_TOOL *ISSUER_SIGN_TOOL_new(void);
void ISSUER_SIGN_TOOL_free(ISSUER_SIGN_TOOL *v);
ISSUER_SIGN_TOOL *d2i_ISSUER_SIGN_TOOL(ISSUER_SIGN_TOOL **a, const unsigned char **pp, long length);
int i2d_ISSUER_SIGN_TOOL(const ISSUER_SIGN_TOOL *a, unsigned char **pp);
=head1 DESCRIPTION
The ISSUER_SIGN_TOOL_new() function returns a new ISSUER_SIGN_TOOL.
ISSUER_SIGN_TOOL_free() frees up a single ISSUER_SIGN_TOOL object.
=head1 RETURN VALUES
ISSUER_SIGN_TOOL_new() returns a newly created ISSUER_SIGN_TOOL or NULL if the call fails.
ISSUER_SIGN_TOOL_free() does not return values.
d2i_ISSUER_SIGN_TOOL() and i2d_ISSUER_SIGN_TOOL() decode and encode an B<ISSUER_SIGN_TOOL>
structure. They otherwise follow the conventions of other ASN.1 functions such as d2i_X509().
=head1 HISTORY
The ISSUER_SIGN_TOOL_up_ref(), ISSUER_SIGN_TOOL_lock() and ISSUER_SIGN_TOOL_unlock()
functions were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OCSP_sendreq_new.pod
+28 -21
View File
@@ -10,22 +10,22 @@ OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions
#include <openssl/ocsp.h>
OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path,
OCSP_REQUEST *req, int maxline);
OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req,
int maxline);
int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx);
void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);
void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx,
unsigned long len);
void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len);
int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
const char *name, const char *value);
int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req);
int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req);
OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
int maxline);
=head1 DESCRIPTION
@@ -35,14 +35,14 @@ response header maximum line length of B<maxline>. If B<maxline> is zero a
default value of 4k is used. The OCSP request B<req> may be set to B<NULL>
and provided later if required.
OCSP_sendreq_nbio() performs I/O on the OCSP request context B<rctx>.
When the operation is complete it returns the response in B<*presp>.
OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context
B<rctx>. When the operation is complete it returns the response in B<*presp>.
OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>.
OCSP_set_max_response_length() sets the maximum response length
for B<rctx> to B<len>. If the response exceeds this length an error occurs.
If not set a default value of 100k is used.
OCSP_set_max_response_length() sets the maximum response length for B<rctx>
to B<len>. If the response exceeds this length an error occurs. If not
set a default value of 100k is used.
OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the
context B<rctx>. It can be called more than once to add multiple headers.
@@ -55,21 +55,23 @@ function should be called after any calls to OCSP_REQ_CTX_add1_header().
OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
path B<path>, the OCSP request B<req> and with a response header maximum line
length 4k. It waits indefinitely on a response.
length of B<maxline>. If B<maxline> is zero a default value of 4k is used.
=head1 RETURN VALUES
OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL>
if an error occurred.
OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if
an error occurred.
OCSP_sendreq_nbio(), OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req()
return B<1> for success and B<0> for failure.
OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully,
B<-1> if the operation should be retried and B<0> if an error occurred.
OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success
and B<0> for failure.
OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the
responder or B<NULL> if an error occurred.
OCSP_REQ_CTX_free() and OCSP_set_max_response_length()
do not return values.
OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values.
=head1 NOTES
@@ -90,9 +92,14 @@ a Host header for B<ocsp.com> you would call:
OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
OCSP_sendreq_bio() does not support timeout nor setting extra headers.
It is retained for compatibility.
Better use B<OCSP_sendreq_nbio()> instead.
If OCSP_sendreq_nbio() indicates an operation should be retried the
corresponding BIO can be examined to determine which operation (read or
write) should be retried and appropriate action taken (for example a select()
call on the underlying socket).
OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking
I/O efficiently. It is retained for compatibility and its use in new
applications is not recommended.
=head1 SEE ALSO
doc/man3/OSSL_CMP_CTX_new.pod
+67 -50
View File
@@ -11,10 +11,12 @@ OSSL_CMP_CTX_set_log_cb,
OSSL_CMP_CTX_set_log_verbosity,
OSSL_CMP_CTX_print_errors,
OSSL_CMP_CTX_set1_serverPath,
OSSL_CMP_CTX_set1_server,
OSSL_CMP_CTX_set1_serverName,
OSSL_CMP_CTX_set_serverPort,
OSSL_CMP_CTX_set1_proxy,
OSSL_CMP_CTX_set1_no_proxy,
OSSL_CMP_CTX_set1_proxyName,
OSSL_CMP_CTX_set_proxyPort,
OSSL_CMP_DEFAULT_PORT,
OSSL_CMP_http_cb_t,
OSSL_CMP_CTX_set_http_cb,
OSSL_CMP_CTX_set_http_cb_arg,
OSSL_CMP_CTX_get_http_cb_arg,
@@ -73,19 +75,22 @@ OSSL_CMP_CTX_set1_senderNonce
/* logging and error reporting: */
int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb);
#define OSSL_CMP_CTX_set_log_verbosity(ctx, level)
void OSSL_CMP_CTX_print_errors(OSSL_CMP_CTX *ctx);
void OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx);
/* message transfer: */
int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
int OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address);
int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);
int OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names);
int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb);
int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port);
#define OSSL_CMP_DEFAULT_PORT 80
typedef BIO *(*OSSL_CMP_http_cb_t)(OSSL_CMP_CTX *ctx, BIO *hbio,
unsigned long detail);
int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_http_cb_t cb);
int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx);
typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx,
OSSL_CMP_transfer_cb_t cb);
int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
@@ -306,7 +311,7 @@ B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host,
also known as "CMP alias".
The default is "/".
The default is I</>.
OSSL_CMP_CTX_set1_server() sets the given server B<address>
(which may be a hostname or IP address or NULL) in the given B<ctx>.
@@ -323,7 +328,7 @@ Otherwise defaults to the value of B<https_proxy> if set, else B<HTTPS_PROXY>.
An empty proxy string specifies not to use a proxy.
Else the format is I<[http[s]://]address[:port][/path]>,
where any path given is ignored.
The default port number is 80, or 443 in case "https:" is given.
The default port number is 80, or 443 in case I<https:> is given.
OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use
an HTTP proxy for. The names may be separated by commas and/or whitespace.
@@ -380,32 +385,40 @@ OSSL_CMP_CTX_get_transfer_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_set_transfer_cb_arg() or NULL if unset.
OSSL_CMP_CTX_set1_srvCert() pins the given server certificate B<srvCert>
directly trusts it (even if it is expired) for verifying response messages.
OSSL_CMP_CTX_set1_srvCert() sets the expected server cert B<srvCert> and trusts
it directly (even if it is expired) when verifying signed response messages.
May be used alternatively to OSSL_CMP_CTX_set0_trustedStore()
to pin the accepted server.
Any previously set value is freed.
The B<cert> argument may be NULL to clear the entry.
If set, the subject of the certificate is also used
as default value for the recipient of CMP requests
and as default value for the expected sender of CMP responses.
OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN) expected to
be given in the sender response for messages protected with MSG_SIG_ALG. This
may be used to enforce that during validation of received messages the given DN
matches the sender field of the PKIMessage header, which in turn is used to
identify the server certificate.
This can be used to ensure that only a particular entity is accepted to act as
CMP server, and attackers are not able to use arbitrary certificates of a
trusted PKI hierarchy to fraudulently pose as server.
This defaults to the subject of the B<srvCert>, if any.
OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN)
expected in the sender field of CMP response messages.
Defaults to the subject of the pinned server certificate B<-srvcert>, if any.
This can be used to make sure that only a particular entity is accepted as
CMP message signer, and attackers are not able to use arbitrary certificates
of a trusted PKI hierarchy to fraudulently pose as CMP server.
Note that this gives slightly more freedom than OSSL_CMP_CTX_set1_srvCert(),
which pins the server to the holder of a particular certificate, while the
expected sender name will continue to match after updates of the server cert.
OSSL_CMP_CTX_set0_trustedStore() sets the X509_STORE type certificate store
containing trusted (root) CA certificates. The certificate store may also hold
CRLs and a certificate verification callback function used for CMP server
authentication. Any already existing store entry is freed. When given a NULL
parameter the entry is cleared.
OSSL_CMP_CTX_set0_trustedStore() sets the certificate store of type X509_STORE
containing trusted (root) CA certificates.
The store may also hold CRLs and
a certificate verification callback function used for CMP server authentication.
Any store entry already set before is freed.
When given a NULL parameter the entry is cleared.
OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the certificate store
containing trusted root CA certificates, which may be empty if unset.
OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the currently set
certificate store containing trusted cert etc., or an empty store if unset.
OSSL_CMP_CTX_set1_untrusted_certs() sets up a list of non-trusted certificates
of intermediate CAs that may be useful for path construction when authenticating
the CMP server and when verifying newly enrolled certificates.
of intermediate CAs that may be useful for path construction for the CMP client
certificate, for the TLS client certificate (if any), when verifying
the CMP server certificate, and when verifying newly enrolled certificates.
The reference counts of those certificates handled successfully are increased.
OSSL_CMP_CTX_get0_untrusted_certs(OSSL_CMP_CTX *ctx) returns a pointer to the
@@ -416,13 +429,13 @@ The public key of this B<cert> must correspond to
the private key set via B<OSSL_CMP_CTX_set1_pkey()>.
When using signature-based protection of CMP request messages
this "protection certificate" will be included first in the extraCerts field.
The subject of this B<cert> will be used as the "sender" field
of outgoing CMP messages, with the fallback being
the B<subjectName> set via B<OSSL_CMP_CTX_set1_subjectName()>.
The subject of this B<cert> will be used as the sender field of outgoing
messages, while the subject of any cert set via B<OSSL_CMP_CTX_set1_oldCert()>
and any value set via B<OSSL_CMP_CTX_set1_subjectName()> are used as fallback.
The B<cert> argument may be NULL to clear the entry.
OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the
protecting certificate B<cert> set via B<OSSL_CMP_CTX_set1_cert()>.
protection certificate B<cert> set via B<OSSL_CMP_CTX_set1_cert()>.
This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG)
of outgoing messages
unless a PBM secret has been set via B<OSSL_CMP_CTX_set1_secretValue()>.
@@ -437,22 +450,25 @@ PBM-based protection takes precedence over signature-based protection.
OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue B<ref> with
length B<len> in the given B<ctx> or clears it if the B<ref> argument is NULL.
According to RFC 4210 section 5.1.1, if no value for the "sender" field in
CMP message headers can be determined (i.e., no protecting certificate B<cert>
and no B<subjectName> is given) then the "sender" field will contain the NULL-DN
According to RFC 4210 section 5.1.1, if no value for the sender field in
CMP message headers can be determined (i.e., no protection certificate B<cert>
and no B<subjectName> is given) then the sender field will contain the NULL-DN
and the senderKID field of the CMP message header must be set.
When signature-based protection is used the senderKID will be set to
the subjectKeyIdentifier of the protecting B<cert> as far as present.
the subjectKeyIdentifier of the protection B<cert> as far as present.
If not present or when PBM-based protection is used
the B<ref> value is taken as the fallback value for the senderKID.
OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
PKIHeader of a request message, i.e. the X509 name of the (CA) server.
Setting is overruled by subject of B<srvCert> if set.
If neither B<srvCert> nor recipient are set, the recipient of the PKI message is
determined in the following order: issuer, issuer of old cert (oldCert),
issuer of protecting certificate (B<cert>), else NULL-DN.
When a response is received, its sender must match the recipient of the request.
PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server.
The recipient field in the header of a CMP message is mandatory.
If not given explicitly the recipient is determined in the following order:
the subject of the CMP server certificate set using OSSL_CMP_CTX_set1_srvCert(),
the value set using OSSL_CMP_CTX_set1_issuer(),
the issuer of the certificate set using OSSL_CMP_CTX_set1_oldCert(),
the issuer of the protection certificate (B<cert>),
as far as any of those is present, else the NULL-DN as last resort.
OSSL_CMP_CTX_push0_geninfo_ITAV() adds B<itav> to the stack in the B<ctx> to be
added to the GeneralInfo field of the CMP PKIMessage header of a request
@@ -480,8 +496,8 @@ the CertTemplate structure when requesting a new cert. For Key Update Requests
(KUR), it defaults to the subject DN of the B<reference certificate>,
see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization
Requests (IR) and Certification Requests (CR) only if no SANs are set.
The B<subjectName> is also used as the "sender" field for outgoing CMP messages
if no B<cert> has been set (e.g., in case requests are protected using PBM).
The B<subjectName> is also used as fallback for the sender field
of outgoing CMP messages if no B<cert> and no B<oldcert> are available.
OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of
alternate names on the certificate template request. This cannot be used if
@@ -507,10 +523,11 @@ to the X509_EXTENSIONS of the requested certificate template.
OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in
Key Update Requests (KUR) or to be revoked in Revocation Requests (RR).
It must be given for RR, else it defaults to the protecting B<cert>.
It must be given for RR, else it defaults to the protection B<cert>.
The B<reference certificate> determined in this way, if any, is also used for
deriving default subject DN and Subject Alternative Names for IR, CR, and KUR.
Its issuer, if any, is used as default recipient in the CMP message header.
Its subject is used as sender in CMP message headers if no protection cert is given.
Its issuer is used as default recipient in CMP message headers.
OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR.
doc/man3/OSSL_CMP_MSG_http_perform.pod
-60
View File
@@ -1,60 +0,0 @@
=pod
=head1 NAME
OSSL_CMP_MSG_http_perform
- client-side HTTP(S) transfer of a CMP request-response pair
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_MSG *OSSL_CMP_MSG_http_perform(OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
=head1 DESCRIPTION
OSSL_CMP_MSG_http_perform() sends the given PKIMessage B<req>
to the CMP server specified in B<ctx> via L<OSSL_CMP_CTX_set1_server(3)>
and optionally L<OSSL_CMP_CTX_set_serverPort(3)>, using
any "CMP alias" optionally specified via L<OSSL_CMP_CTX_set1_serverPath(3)>.
The default port is 80 for HTTP and 443 for HTTPS; the default path is "/".
On success the function returns the server's response PKIMessage.
The function makes use of any HTTP callback function
set via L<OSSL_CMP_CTX_set_http_cb(3)>.
It respects any timeout value set via L<OSSL_CMP_CTX_set_option(3)>
with an B<OSSL_CMP_OPT_MSG_TIMEOUT> argument.
It also respects any HTTP(S) proxy options set via L<OSSL_CMP_CTX_set1_proxy(3)>
and L<OSSL_CMP_CTX_set1_no_proxy(3)> and the respective environment variables.
Proxying plain HTTP is supported directly,
while using a proxy for HTTPS connections requires a suitable callback function
such as L<OSSL_HTTP_proxy_connect(3)>.
=head1 NOTES
CMP is defined in RFC 4210.
HTTP transfer for CMP is defined in RFC 6712.
=head1 RETURN VALUES
OSSL_CMP_MSG_http_perform() returns a CMP message on success, else NULL.
=head1 SEE ALSO
L<OSSL_CMP_CTX_new(3)>, L<OSSL_HTTP_proxy_connect(3)>.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_SRV_CTX_new.pod
+9 -8
View File
@@ -85,32 +85,33 @@ OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
=head1 DESCRIPTION
OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
It does the typical generic checks on the given request message, calls
Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
I<req>. It does the typical generic checks on I<req>, calls
the respective callback function (if present) for more specific processing,
and then assembles a result message, which may be a CMP error message.
OSSL_CMP_CTX_server_perform() is an interface to
B<OSSL_CMP_SRV_process_request()> that can be used by a CMP client
in the same way as B<OSSL_CMP_MSG_http_perform()>.
The B<OSSL_CMP_SRV_CTX> must be set as B<transfer_cb_arg> of B<client_ctx>.
The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.
OSSL_CMP_SRV_CTX_new() creates and initializes an OSSL_CMP_SRV_CTX structure
and returns a pointer to it on success, NULL on error.
OSSL_CMP_SRV_CTX_free() deletes the given B<srv_ctx>.
OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.
OSSL_CMP_SRV_CTX_init() sets in the given B<srv_ctx> a custom server context
OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
pointer as well as callback functions performing the specific processing of CMP
certificate requests, revocation requests, certificate confirmation requests,
general messages, error messages, and poll requests.
All arguments except B<srv_ctx> may be NULL.
All arguments except I<srv_ctx> may be NULL.
If a callback for some message type is not given this means that the respective
type of CMP message is not supported by the server.
OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the B<srv_ctx>.
OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
B<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init>.
I<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init()>.
OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
and other forms of negative responses unprotected.
@@ -142,7 +143,7 @@ OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
NULL on error.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
that has been set using B<OSSL_CMP_SRV_CTX_init>.
that has been set using B<OSSL_CMP_SRV_CTX_init()>.
All other functions return 1 on success, 0 on error.
doc/man3/OSSL_CMP_validate_msg.pod
-7
View File
@@ -46,13 +46,6 @@ according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
Any cert that has been found as described above is cached and tried first when
validating the signatures of subsequent messages in the same transaction.
After successful validation of PBM-based protection of a certificate response
the certificates in the caPubs field (if any) are added to the trusted
certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>, such that
they are available for validating subsequent messages in the same context.
Those could apply to any Polling Response (pollRep), error, or PKI Confirmation
(PKIConf) messages following in the same or future transactions.
OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its
path using the given store of trusted certs (possibly including CRLs and a cert
verification callback) and non-trusted intermediate certs from the B<ctx>.
doc/man3/OSSL_HTTP_transfer.pod
-233
View File
@@ -1,233 +0,0 @@
=pod
=head1 NAME
OSSL_HTTP_get,
OSSL_HTTP_get_asn1,
OSSL_HTTP_post_asn1,
OSSL_HTTP_transfer,
OSSL_HTTP_bio_cb_t,
OSSL_HTTP_proxy_connect,
OSSL_HTTP_parse_url
- http client functions
=head1 SYNOPSIS
#include <openssl/http.h>
typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
int connect, int detail);
BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
int maxline, unsigned long max_resp_len, int timeout,
const char *expected_content_type, int expect_asn1);
ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url,
const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
int maxline, unsigned long max_resp_len,
int timeout, const char *expected_content_type,
const ASN1_ITEM *it);
ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port,
const char *path, int use_ssl,
const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
const char *content_type,
const ASN1_VALUE *req, const ASN1_ITEM *req_it,
int maxline, unsigned long max_resp_len,
int timeout, const char *expected_ct,
const ASN1_ITEM *rsp_it);
BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path,
int use_ssl, const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
const char *content_type, BIO *req_mem,
int maxline, unsigned long max_resp_len, int timeout,
const char *expected_ct, int expect_asn1,
char **redirection_url);
int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port,
const char *proxyuser, const char *proxypass,
int timeout, BIO *bio_err, const char *prog);
int OSSL_HTTP_parse_url(const char *url, char **phost, char **pport,
char **ppath, int *pssl);
=head1 DESCRIPTION
OSSL_HTTP_get() uses HTTP GET to obtain data (of any type) from the given B<url>
and returns it as a memory BIO.
OSSL_HTTP_get_asn1() uses HTTP GET to obtain an ASN.1-encoded value
(e.g., an X.509 certificate) with the expected structure specified by B<it>
(e.g., I<ASN1_ITEM_rptr(X509)>) from the given B<url>
and returns it on success as a pointer to I<ASN1_VALUE>.
OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request B<req>
with the ASN.1 structure defined in B<req_it> and the given B<content_type> to
the given B<server> and optional B<port> and B<path>.
If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
parameter, described below, must be provided.
The optional list B<headers> may contain additional custom HTTP header lines.
The expected structure of the response is specified by B<rsp_it>.
On success it returns the response as a pointer to B<ASN1_VALUE>.
OSSL_HTTP_transfer() exchanges any form of HTTP request and response.
It implements the core of the functions described above.
If B<path> parameter is NULL it defaults to "/".
If B<use_ssl> is nonzero a TLS connection is requested
and the B<bio_update_fn> parameter, described below, must be provided.
If B<req_mem> is NULL it uses the HTTP GET method, else it uses HTTP POST to
send a request with the contents of the memory BIO and optional B<content_type>.
The optional list B<headers> may contain additional custom HTTP header lines.
If B<req_mem> is NULL (i.e., the HTTP method is GET) and B<redirection_url>
is not NULL the latter pointer is used to provide any new location that
the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND).
In this case the caller is responsible for deallocating this URL with
L<OPENSSL_free(3)>.
The above functions have the following parameters in common.
Typically the OpenSSL build supports sockets
and the B<bio> and B<rbio> parameters are both NULL.
In this case the client creates a network BIO internally
for connecting to the given B<server>
at the specified B<port> (if any, defaulting to 80 for HTTP or 443 for HTTPS),
optionally via a B<proxy> (respecting B<no_proxy>) as described below.
Then the client uses this internal BIO for exchanging the request and response.
If B<bio> is given and B<rbio> is NULL then the client uses this B<bio> instead.
If both B<bio> and B<rbio> are given (which may be memory BIOs for instance)
then no explicit connection is attempted,
B<bio> is used for writing the request, and B<rbio> for reading the response.
As soon as the client has flushed B<bio> the server must be ready to provide
a response or indicate a waiting condition via B<rbio>.
The optional B<proxy> parameter can be used to set the address of the an
HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
If TLS is not used this defaults to the environment variable B<http_proxy>
if set, else B<HTTP_PROXY>.
If B<use_ssl> != 0 it defaults to B<https_proxy> if set, else B<HTTPS_PROXY>.
An empty proxy string specifies not to use a proxy.
Else the format is I<[http[s]://]address[:port][/path]>,
where any path given is ignored.
The default proxy port number is 80, or 443 in case "https:" is given.
The HTTP client functions connect via the given proxy unless the B<server>
is found in the optional list B<no_proxy> of proxy hostnames (if not NULL;
default is the environment variable B<no_proxy> if set, else B<NO_PROXY>).
Proxying plain HTTP is supported directly,
while using a proxy for HTTPS connections requires a suitable callback function
such as B<OSSL_HTTP_proxy_connect()>, described below.
The B<maxline> parameter specifies the response header maximum line length,
where 0 indicates the default value, which currently is 4k.
The B<max_resp_len> parameter specifies the maximum response length,
where 0 indicates the default value, which currently is 100k.
An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
this is only the case if the B<expect_asn1> parameter is nonzero.
If the response header contains one or more "Content-Length" header lines and/or
an ASN.1-encoded response is expected, which should include a total length,
the length indications received are checked for consistency
and for not exceeding the maximum response length.
If the parameter B<expected_content_type> (or B<expected_ct>, respectively)
is not NULL then the HTTP client checks that the given content type string
is included in the HTTP header of the response and returns an error if not.
If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
to wait until the transfer is complete.
A value of 0 enables waiting indefinitely,
while a value < 0 immediately leads to a timeout condition.
The optional parameter B<bio_update_fn> with its optional argument B<arg> may
be used to modify the connection BIO used by the HTTP client (and cannot be
used when both B<bio> and B<rbio> are given).
B<bio_update_fn> is a BIO connect/disconnect callback function with prototype
BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
The callback may modify the HTTP BIO provided in the B<bio> argument,
whereby it may make use of a custom defined argument B<arg>,
which may for instance refer to an I<SSL_CTX> structure.
During connection establishment, just after calling BIO_connect_retry(),
the function is invoked with the B<connect> argument being 1 and the B<detail>
argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled.
On disconnect B<connect> is 0 and B<detail> is 1 if no error occurred, else 0.
For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
after disconnect it may do some diagnostic output and/or specific cleanup.
The function should return NULL to indicate failure.
Here is a simple example that supports TLS connections (but not via a proxy):
BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
{
SSL_CTX *ctx = (SSL_CTX *)arg;
if (connect && detail) { /* connecting with TLS */
BIO *sbio = BIO_new_ssl(ctx, 1);
hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL;
} else if (!connect && !detail) { /* disconnecting after error */
/* optionally add diagnostics here */
}
return hbio;
}
After disconnect the modified BIO will be deallocated using BIO_free_all().
OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function
to set up an SSL/TLS connection via an HTTPS proxy.
It promotes the given BIO B<bio> representing a connection
pre-established with a TLS proxy using the HTTP CONNECT method,
optionally using proxy client credentials B<proxyuser> and B<proxypass>,
to connect with TLS protection ultimately to B<server> and B<port>.
If the B<port> argument is NULL or the empty string it defaults to "443".
The B<timeout> parameter is used as described above.
Since this function is typically called by appplications such as
L<openssl-s_client(1)> it uses the B<bio_err> and B<prog> parameters (unless
NULL) to print additional diagnostic information in a user-oriented way.
OSSL_HTTP_parse_url() parses its input string B<url> as a URL and splits it up
into host, port and path components and a flag whether it begins with 'https'.
The host component may be a DNS name or an IPv4 or an IPv6 address.
The port component is optional and defaults to "443" for HTTPS, else "80".
The path component is also optional and defaults to "/".
As far as the result pointer arguments are not NULL it assigns via
them copies of the respective string components.
The strings returned this way must be deallocated by the caller using
L<OPENSSL_free(3)> unless they are NULL, which is their default value on error.
=head1 NOTES
The names of the environment variables used by this implementation:
B<http_proxy>, B<HTTP_PROXY>, B<https_proxy>, B<HTTPS_PROXY>, B<no_proxy>, and
B<NO_PROXY>, have been chosen for maximal compatibility with
other HTTP client implementations such as wget, curl, and git.
=head1 RETURN VALUES
OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL.
Error conditions include connection/transfer timeout, parse errors, etc.
OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url()
return 1 on success, 0 on error.
=head1 HISTORY
OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(),
OSSL_HTTP_proxy_connect(), and OSSL_HTTP_parse_url() were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_PARAM_allocate_from_text.pod
+1 -1
View File
@@ -175,7 +175,7 @@ Can be written like this instead:
goto err;
}
params[params_n] = OSSL_PARAM_construct_end();
if (!EVP_MAC_CTX_set_params(ctx, params))
if (!EVP_MAC_set_ctx_params(ctx, params))
goto err;
while (params_n-- > 0)
OPENSSL_free(params[params_n].data);
doc/man3/OSSL_PROVIDER.pod
+31 -1
View File
@@ -4,8 +4,9 @@
OSSL_PROVIDER_set_default_search_path,
OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload,
OSSL_PROVIDER_available,
OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
OSSL_PROVIDER_query_operation, OSSL_PROVIDER_get0_provider_ctx,
OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines
=head1 SYNOPSIS
@@ -20,10 +21,18 @@ OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines
OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *libctx, const char *name);
int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_available(OPENSSL_CTX *libctx, const char *name);
int OSSL_PROVIDER_do_all(OPENSSL_CTX *ctx,
int (*cb)(OSSL_PROVIDER *provider, void *cbdata),
void *cbdata);
const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);
const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov,
int operation_id,
int *no_cache);
void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *libctx, const char *name,
ossl_provider_init_fn *init_fn);
@@ -66,6 +75,10 @@ runs its teardown function.
OSSL_PROVIDER_available() checks if a named provider is available
for use.
OSSL_PROVIDER_do_all() iterates over all loaded providers, calling
I<cb> for each one, with the current provider in I<provider> and the
I<cbdata> that comes from the caller.
OSSL_PROVIDER_gettable_params() is used to get a provider parameter
descriptor set as a constant B<OSSL_PARAM> array.
See L<OSSL_PARAM(3)> for more information.
@@ -75,6 +88,20 @@ The caller must prepare the B<OSSL_PARAM> array before calling this
function, and the variables acting as buffers for this parameter array
should be filled with data when it returns successfully.
OSSL_PROVIDER_query_operation() calls the provider's I<query_operation>
function (see L<provider(7)>), if the provider has one. It returns an
array of I<OSSL_ALGORITHM> for the given I<operation_id> terminated by an all
NULL OSSL_ALGORITHM entry. This is considered a low-level function that most
applications should not need to call.
OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given
provider. The provider context is an opaque handle set by the provider itself
and is passed back to the provider by libcrypto in various function calls.
If it is permissible to cache references to this array then I<*no_store> is set
to 0 or 1 otherwise. If the array is not cacheable then it is assumed to
have a short lifetime.
OSSL_PROVIDER_name() returns the name of the given provider.
=head1 RETURN VALUES
@@ -94,6 +121,9 @@ of constant B<OSSL_PARAM>, or NULL if none is provided.
OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error.
OSSL_PROVIDER_query_operation() returns an array of OSSL_ALGORITHM or NULL on
error.
=head1 EXAMPLES
This demonstrates how to load the provider module "foo" and ask for
doc/man3/OSSL_STORE_INFO.pod
+12 -17
View File
@@ -54,25 +54,24 @@ loaders to create B<OSSL_STORE_INFO> holders.
=head2 Types
B<OSSL_STORE_INFO> is an opaque type that's just an intermediary holder for
the objects that have been retrieved by OSSL_STORE_load() and similar
functions.
the objects that have been retrieved by OSSL_STORE_load() and similar functions.
Supported OpenSSL type object can be extracted using one of
STORE_INFO_get0_TYPE().
STORE_INFO_get0_<TYPE>() where <TYPE> can be NAME, PARAMS, PKEY, CERT, or CRL.
The life time of this extracted object is as long as the life time of
the B<OSSL_STORE_INFO> it was extracted from, so care should be taken not
to free the latter too early.
As an alternative, STORE_INFO_get1_TYPE() extracts a duplicate (or the
As an alternative, STORE_INFO_get1_<TYPE>() extracts a duplicate (or the
same object with its reference count increased), which can be used
after the containing B<OSSL_STORE_INFO> has been freed.
The object returned by STORE_INFO_get1_TYPE() must be freed separately
The object returned by STORE_INFO_get1_<TYPE>() must be freed separately
by the caller.
See L</SUPPORTED OBJECTS> for more information on the types that are
supported.
See L</SUPPORTED OBJECTS> for more information on the types that are supported.
=head2 Functions
OSSL_STORE_INFO_get_type() takes a B<OSSL_STORE_INFO> and returns the STORE
type number for the object inside.
STORE_INFO_get_type_string() takes a STORE type number and returns a
short string describing it.
@@ -94,6 +93,8 @@ OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
OSSL_STORE_INFO_new_CRL() create a B<OSSL_STORE_INFO>
object to hold the given input object.
On success the input object is consumed.
Additionally, for B<OSSL_STORE_INFO_NAME>` objects,
OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
description.
@@ -162,9 +163,9 @@ OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
a pointer to the OpenSSL object on success, NULL otherwise.
OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all return
a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
OSSL_STORE_INFO_type_string() returns a string on success, or B<NULL> on
@@ -184,13 +185,7 @@ L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)>
=head1 HISTORY
OSSL_STORE_INFO(), OSSL_STORE_INFO_get_type(), OSSL_STORE_INFO_get0_NAME(),
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
OSSL_STORE_INFO_get0_CERT(), OSSL_STORE_INFO_get0_CRL(),
OSSL_STORE_INFO_type_string(), OSSL_STORE_INFO_free(), OSSL_STORE_INFO_new_NAME(),
OSSL_STORE_INFO_new_PARAMS(), OSSL_STORE_INFO_new_PKEY(),
OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL()
were added in OpenSSL 1.1.1.
The OSSL_STORE API was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
doc/man3/OSSL_STORE_open.pod
+18 -13
View File
@@ -46,21 +46,22 @@ OSSL_STORE_close() to work together.
=head2 Functions
OSSL_STORE_open() takes a uri or path B<uri>, password UI method
B<ui_method> with associated data B<ui_data>, and post processing
callback B<post_process> with associated data B<post_process_data>,
OSSL_STORE_open() takes a uri or path I<uri>, password UI method
I<ui_method> with associated data I<ui_data>, and post processing
callback I<post_process> with associated data I<post_process_data>,
opens a channel to the data located at that URI and returns a
B<OSSL_STORE_CTX> with all necessary internal information.
The given B<ui_method> and B<ui_data_data> will be reused by all
functions that use B<OSSL_STORE_CTX> when interaction is needed.
The given B<post_process> and B<post_process_data> will be reused by
The given I<ui_method> and I<ui_data> will be reused by all
functions that use B<OSSL_STORE_CTX> when interaction is needed,
for instance to provide a password.
The given I<post_process> and I<post_process_data> will be reused by
OSSL_STORE_load() to manipulate or drop the value to be returned.
The B<post_process> function drops values by returning B<NULL>, which
The I<post_process> function drops values by returning NULL, which
will cause OSSL_STORE_load() to start its process over with loading
the next object, until B<post_process> returns something other than
B<NULL>, or the end of data is reached as indicated by OSSL_STORE_eof().
the next object, until I<post_process> returns something other than
NULL, or the end of data is reached as indicated by OSSL_STORE_eof().
OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number I<cmd> and
more arguments not specified here.
The available loader specific command numbers and arguments they each
take depends on the loader that's used and is documented together with
@@ -94,6 +95,7 @@ OSSL_STORE_eof() shows that the end of data has been reached.
OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened
by OSSL_STORE_open() and frees all other information that was stored in the
B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself.
If I<ctx> is NULL it does nothing.
=head1 SUPPORTED SCHEMES
@@ -123,12 +125,12 @@ See L<passphrase-encoding(7)> for further information.
=head1 RETURN VALUES
OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or
B<NULL> on failure.
NULL on failure.
OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or
B<NULL> on error or when end of data is reached.
NULL on error or when end of data is reached.
Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a
returned B<NULL>.
returned NULL.
OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise
0.
@@ -149,6 +151,9 @@ OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(),
OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close()
were added in OpenSSL 1.1.1.
Handling of NULL I<ctx> argument for OSSL_STORE_close()
was introduced in OpenSSL 1.1.1h.
=head1 COPYRIGHT
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_trace_set_channel.pod
+2 -2
View File
@@ -178,9 +178,9 @@ point during evaluation.
Traces BIGNUM context operations.
=item C<OSSL_TRACE_CATEGORY_PROVIDER_CONF>
=item C<OSSL_TRACE_CATEGORY_CONF>
Traces the OSSL_PROVIDER configuration.
Traces details about the provider and engine configuration.
=back
doc/man3/SSL_CIPHER_get_name.pod
+13
View File
@@ -13,6 +13,7 @@ SSL_CIPHER_get_digest_nid,
SSL_CIPHER_get_handshake_digest,
SSL_CIPHER_get_kx_nid,
SSL_CIPHER_get_auth_nid,
SSL_CIPHER_get_prf_nid,
SSL_CIPHER_is_aead,
SSL_CIPHER_find,
SSL_CIPHER_get_id,
@@ -34,6 +35,7 @@ SSL_CIPHER_get_protocol_id
const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c);
int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_prf_nid(const SSL_CIPHER *c);
int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr);
uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c);
@@ -91,6 +93,15 @@ TLS 1.3 cipher suites) B<NID_auth_any> is returned. Examples (not comprehensive)
NID_auth_ecdsa
NID_auth_psk
SSL_CIPHER_get_prf_nid() retuns the pseudo-random function NID for B<c>. If B<c> is
a pre-TLS-1.2 cipher, it returns B<NID_md5_sha1> but note these ciphers use
SHA-256 in TLS 1.2. Other return values may be treated uniformly in all
applicable versions. Examples (not comprehensive):
NID_md5_sha1
NID_sha256
NID_sha384
SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
ChaCha20/Poly1305), and 0 if it is not AEAD.
@@ -201,6 +212,8 @@ required to enable this function.
The OPENSSL_cipher_name() function was added in OpenSSL 1.1.1.
The SSL_CIPHER_get_prf_nid() function was added in OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/SSL_CTX_load_verify_locations.pod
+6 -10
View File
@@ -22,20 +22,16 @@ SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations
int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
int SSL_CTX_set_default_verify_store(SSL_CTX *ctx);
Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
const char *CApath);
=head1 DESCRIPTION
SSL_CTX_load_verify_dir(), SSL_CTX_load_verify_file(),
SSL_CTX_load_verify_store() specifies the locations for B<ctx>, at
which CA certificates for verification purposes are located. The
certificates available via B<CAfile>, B<CApath> and B<CAstore> are
trusted.
SSL_CTX_load_verify_locations(), SSL_CTX_load_verify_dir(),
SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store() specifies the
locations for B<ctx>, at which CA certificates for verification purposes
are located. The certificates available via B<CAfile>, B<CApath> and
B<CAstore> are trusted.
SSL_CTX_set_default_verify_paths() specifies that the default locations from
which CA certificates are loaded should be used. There is one default directory,
@@ -176,7 +172,7 @@ L<SSL_CTX_set_client_CA_list(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/SSL_CTX_set_options.pod
+17 -2
View File
@@ -217,6 +217,20 @@ not propose, and servers will not accept the extension.
Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
messages, and ignore renegotiation requests via ClientHello.
=item SSL_OP_IGNORE_UNEXPECTED_EOF
Some TLS implementations do not send the mandatory close_notify alert on
shutdown. If the application tries to wait for the close_notify alert but the
peer closes the connection without sending it, an error is generated. When this
option is enabled the peer does not need to send the close_notify alert and a
closed connection will be treated as if the close_notify alert was received.
You should only enable this option if the protocol running over TLS
can detect a truncation attack itself, and that the application is checking for
that truncation attack.
For more information on shutting down a connection, see L<SSL_shutdown(3)>.
=item SSL_OP_ALLOW_NO_DHE_KEX
In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
@@ -367,7 +381,7 @@ secure renegotiation and 0 if it does not.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>,
L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_shutdown(3)>
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<SSL_CTX_set_min_proto_version(3)>,
L<openssl-dhparam(1)>
@@ -380,7 +394,8 @@ OpenSSL 0.9.8m.
The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
were added in OpenSSL 1.1.1.
The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> option was added in OpenSSL 3.0.
The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> and B<SSL_OP_IGNORE_UNEXPECTED_EOF>
options were added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_psk_client_callback.pod
+4 -2
View File
@@ -123,7 +123,9 @@ and it will use that in preference. If no such callback is present then it will
check to see if a callback has been set via SSL_CTX_set_psk_client_callback() or
SSL_set_psk_client_callback() and use that. In this case the B<hint> value will
always be NULL and the handshake digest will default to SHA-256 for any returned
PSK.
PSK. TLSv1.3 early data exchanges are possible in PSK connections only with the
B<SSL_psk_use_session_cb_func> callback, and are not possible with the
B<SSL_psk_client_cb_func> callback.
=head1 NOTES
@@ -167,7 +169,7 @@ were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/SSL_CTX_set_quic_method.pod
+232
View File
@@ -0,0 +1,232 @@
=pod
=head1 NAME
SSL_QUIC_METHOD,
OSSL_ENCRYPTION_LEVEL,
SSL_CTX_set_quic_method,
SSL_set_quic_method,
SSL_set_quic_transport_params,
SSL_get_peer_quic_transport_params,
SSL_quic_max_handshake_flight_len,
SSL_quic_read_level,
SSL_quic_write_level,
SSL_provide_quic_data,
SSL_process_quic_post_handshake,
SSL_is_quic
- QUIC support
=head1 SYNOPSIS
#include <openssl/ssl.h>
typedef struct ssl_quic_method_st SSL_QUIC_METHOD;
typedef enum ssl_encryption_level_t OSSL_ENCRYPTION_LEVEL;
int SSL_CTX_set_quic_method(SSL_CTX *ctx, const SSL_QUIC_METHOD *quic_method);
int SSL_set_quic_method(SSL *ssl, const SSL_QUIC_METHOD *quic_method);
int SSL_set_quic_transport_params(SSL *ssl,
const uint8_t *params,
size_t params_len);
void SSL_get_peer_quic_transport_params(const SSL *ssl,
const uint8_t **out_params,
size_t *out_params_len);
size_t SSL_quic_max_handshake_flight_len(const SSL *ssl, OSSL_ENCRYPTION_LEVEL level);
OSSL_ENCRYPTION_LEVEL SSL_quic_read_level(const SSL *ssl);
OSSL_ENCRYPTION_LEVEL SSL_quic_write_level(const SSL *ssl);
int SSL_provide_quic_data(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
const uint8_t *data, size_t len);
int SSL_process_quic_post_handshake(SSL *ssl);
int SSL_is_quic(SSL *ssl);
=head1 DESCRIPTION
SSL_CTX_set_quic_method() and SSL_set_quic_method() configures the QUIC methods.
This should only be configured with a minimum version of TLS 1.3. B<quic_method>
must remain valid for the lifetime of B<ctx> or B<ssl>. Calling this disables
the SSL_OP_ENABLE_MIDDLEBOX_COMPAT option, which is not required for QUIC.
SSL_set_quic_transport_params() configures B<ssl> to send B<params> (of length
B<params_len>) in the quic_transport_parameters extension in either the
ClientHello or EncryptedExtensions handshake message. This extension will
only be sent if the TLS version is at least 1.3, and for a server, only if
the client sent the extension. The buffer pointed to by B<params> only need be
valid for the duration of the call to this function.
SSL_get_peer_quic_transport_params() provides the caller with the value of the
quic_transport_parameters extension sent by the peer. A pointer to the buffer
containing the TransportParameters will be put in B<*out_params>, and its
length in B<*out_params_len>. This buffer will be valid for the lifetime of the
B<ssl>. If no params were received from the peer, B<*out_params_len> will be 0.
SSL_quic_max_handshake_flight_len() returns the maximum number of bytes
that may be received at the given encryption level. This function should be
used to limit buffering in the QUIC implementation.
See https://tools.ietf.org/html/draft-ietf-quic-transport-16#section-4.4.
SSL_quic_read_level() returns the current read encryption level.
SSL_quic_write_level() returns the current write encryption level.
SSL_provide_quic_data() provides data from QUIC at a particular encryption
level B<level>. It is an error to call this function outside of the handshake
or with an encryption level other than the current read level. It returns one
on success and zero on error.
SSL_process_quic_post_handshake() processes any data that QUIC has provided
after the handshake has completed. This includes NewSessionTicket messages
sent by the server.
SSL_is_quic() indicates whether a connection uses QUIC.
=head1 NOTES
These APIs are implementations of BoringSSL's QUIC APIs.
QUIC acts as an underlying transport for the TLS 1.3 handshake. The following
functions allow a QUIC implementation to serve as the underlying transport as
described in draft-ietf-quic-tls.
When configured for QUIC, SSL_do_handshake() will drive the handshake as
before, but it will not use the configured B<BIO>. It will call functions on
B<SSL_QUIC_METHOD> to configure secrets and send data. If data is needed from
the peer, it will return B<SSL_ERROR_WANT_READ>. When received, the caller
should call SSL_provide_quic_data() and then SSL_do_handshake() to continue
the handshake. After the handshake is complete, the caller should call
SSL_provide_quic_data() for any post-handshake data, followed by
SSL_process_quic_post_handshake() to process it. It is an error to call
SSL_read()/SSL_read_ex() and SSL_write()/SSL_write_ex() in QUIC.
Note that secrets for an encryption level may be available to QUIC before the
level is active in TLS. Callers should use SSL_quic_read_level() to determine
the active read level for SSL_provide_quic_data(). SSL_do_handshake() will
pass the active write level to add_handshake_data() when writing data. Callers
can use SSL_quic_write_level() to query the active write level when
generating their own errors.
See https://tools.ietf.org/html/draft-ietf-quic-tls-15#section-4.1 for more
details.
To avoid DoS attacks, the QUIC implementation must limit the amount of data
being queued up. The implementation can call
SSL_quic_max_handshake_flight_len() to get the maximum buffer length at each
encryption level.
draft-ietf-quic-tls defines a new TLS extension quic_transport_parameters
used by QUIC for each endpoint to unilaterally declare its supported
transport parameters. draft-ietf-quic-transport (section 7.4) defines the
contents of that extension (a TransportParameters struct) and describes how
to handle it and its semantic meaning.
OpenSSL handles this extension as an opaque byte string. The caller is
responsible for serializing and parsing it.
=head2 OSSL_ENCRYPTION_LEVEL
B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>) represents the
encryption levels:
=over 4
=item ssl_encryption_initial
The initial encryption level that is used for client and server hellos.
=item ssl_encryption_early_data
The encryption level for early data. This is a write-level for the client
and a read-level for the server.
=item ssl_encryption_handshake
The encryption level for the remainder of the handshake.
=item ssl_encryption_application
The encryption level for the application data.
=back
=head2 SSL_QUIC_METHOD
The B<SSL_QUIC_METHOD> (B<struct ssl_quic_method_st>) describes the
QUIC methods.
struct ssl_quic_method_st {
int (*set_encryption_secrets)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
const uint8_t *read_secret,
const uint8_t *write_secret, size_t secret_len);
int (*add_handshake_data)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
const uint8_t *data, size_t len);
int (*flush_flight)(SSL *ssl);
int (*send_alert)(SSL *ssl, enum ssl_encryption_level_t level, uint8_t alert);
};
typedef struct ssl_quic_method_st SSL_QUIC_METHOD;
set_encryption_secrets() configures the read and write secrets for the given
encryption level. This function will always be called before an encryption
level other than B<ssl_encryption_initial> is used. Note, however, that
secrets for a level may be configured before TLS is ready to send or accept
data at that level.
When reading packets at a given level, the QUIC implementation must send
ACKs at the same level, so this function provides read and write secrets
together. The exception is B<ssl_encryption_early_data>, where secrets are
only available in the client to server direction. The other secret will be
NULL. The server acknowledges such data at B<ssl_encryption_application>,
which will be configured in the same SSL_do_handshake() call.
This function should use SSL_get_current_cipher() to determine the TLS
cipher suite.
add_handshake_data() adds handshake data to the current flight at the given
encryption level. It returns one on success and zero on error.
OpenSSL will pack data from a single encryption level together, but a
single handshake flight may include multiple encryption levels. Callers
should defer writing data to the network until flush_flight() to better
pack QUIC packets into transport datagrams.
flush_flight() is called when the current flight is complete and should be
written to the transport. Note a flight may contain data at several
encryption levels.
send_alert() sends a fatal alert at the specified encryption level.
All QUIC methods return 1 on success and 0 on error.
=head1 RETURN VALUES
SSL_CTX_set_quic_method(),
SSL_set_quic_method(),
SSL_set_quic_transport_params(), and
SSL_process_quic_post_handshake()
return 1 on success, and 0 on error.
SSL_quic_read_level() and SSL_quic_write_level() return the current
encryption level as B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>).
SSL_quic_max_handshake_flight_len() returns the maximum length of a flight
for a given encryption level.
SSL_is_quic() returns 1 if QUIC is being used, 0 if not.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_CIPHER_get_prf_nid(3)>, L<SSL_do_handshake(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/SSL_CTX_set_record_padding_callback.pod
+9 -1
View File
@@ -16,7 +16,7 @@ SSL_set_block_padding - install callback to specify TLS 1.3 record padding
#include <openssl/ssl.h>
void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
void SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
int SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx);
@@ -32,6 +32,8 @@ SSL_set_block_padding - install callback to specify TLS 1.3 record padding
SSL_CTX_set_record_padding_callback() or SSL_set_record_padding_callback()
can be used to assign a callback function I<cb> to specify the padding
for TLS 1.3 records. The value set in B<ctx> is copied to a new SSL by SSL_new().
Kernel TLS is not possible if the record padding callback is set, and the callback
function cannot be set if Kernel TLS is already configured for the current SSL object.
SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg()
assign a value B<arg> that is passed to the callback when it is invoked. The value
@@ -64,6 +66,9 @@ indicates no padding will be added. A return value that causes the record to
exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the
maximum record size.
The SSL_CTX_get_record_padding_callback_arg() function returns 1 on success or 0 if
the callback function is not set because Kernel TLS is configured for the SSL object.
=head1 NOTES
The default behavior is to add no padding to the record.
@@ -84,6 +89,9 @@ L<ssl(7)>, L<SSL_new(3)>
The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1.
The return type of SSL_CTX_set_record_padding_callback() function was
changed to int in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/SSL_CTX_set_session_ticket_cb.pod
+1 -1
View File
@@ -177,7 +177,7 @@ L<SSL_get_session(3)>
=head1 HISTORY
The SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata()
The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata()
and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+7 -7
View File
@@ -49,7 +49,7 @@ ticket information or it starts a full TLS handshake to create a new session
ticket.
Before the callback function is started I<ctx> and I<hctx> have been
initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_CTX_new(3)>
initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_new_ctx(3)>
respectively.
For new sessions tickets, when the client doesn't present a session ticket, or
@@ -66,7 +66,7 @@ maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
The initialization vector I<iv> should be a random value. The cipher context
I<ctx> should use the initialisation vector I<iv>. The cipher context can be
set using L<EVP_EncryptInit_ex(3)>. The hmac context and digest can be set using
L<EVP_MAC_CTX_set_params(3)> with the B<OSSL_MAC_PARAM_KEY> and
L<EVP_MAC_set_ctx_params(3)> with the B<OSSL_MAC_PARAM_KEY> and
B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
When the client presents a session ticket, the callback function with be called
@@ -76,7 +76,7 @@ the session ticket. The OpenSSL library expects that the I<name> will be used
to retrieve a cryptographic parameters and that the cryptographic context
I<ctx> will be set with the retrieved parameters and the initialization vector
I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The key material and
digest for I<hctx> need to be set using L<EVP_MAC_CTX_set_params(3)> with the
digest for I<hctx> need to be set using L<EVP_MAC_set_ctx_params(3)> with the
B<OSSL_MAC_PARAM_KEY> and B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
If the I<name> is still valid but a renewal of the ticket is required the
@@ -120,8 +120,8 @@ The SSL_CTX_set_tlsext_ticket_key_cb() function is identical to
SSL_CTX_set_tlsext_ticket_key_evp_cb() except that it takes a deprecated
HMAC_CTX pointer instead of an EVP_MAC_CTX one.
Before this callback function is started I<hctx> will have been
initialised with L<EVP_MAC_CTX_new(3)> and the digest set with
L<EVP_MAC_CTX_set_params(3)>.
initialised with L<EVP_MAC_new_ctx(3)> and the digest set with
L<EVP_MAC_set_ctx_params(3)>.
The I<hctx> key material can be set using L<HMAC_Init_ex(3)>.
=head1 NOTES
@@ -185,7 +185,7 @@ Reference Implementation:
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
"sha256", 0);
params[2] = OSSL_PARAM_construct_end();
EVP_MAC_CTX_set_params(hctx, params);
EVP_MAC_set_ctx_params(hctx, params);
return 1;
@@ -200,7 +200,7 @@ Reference Implementation:
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
"sha256", 0);
params[2] = OSSL_PARAM_construct_end();
EVP_MAC_CTX_set_params(hctx, params);
EVP_MAC_set_ctx_params(hctx, params);
EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
doc/man3/SSL_CTX_use_psk_identity_hint.pod
+4 -2
View File
@@ -83,7 +83,9 @@ via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback
and it will use that in preference. If no such callback is present then it will
check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or
SSL_set_psk_server_callback() and use that. In this case the handshake digest
will default to SHA-256 for any returned PSK.
will default to SHA-256 for any returned PSK. TLSv1.3 early data exchanges are
possible in PSK connections only with the B<SSL_psk_find_session_cb_func>
callback, and are not possible with the B<SSL_psk_server_cb_func> callback.
A connection established via a TLSv1.3 PSK will appear as if session resumption
has occurred so that L<SSL_session_reused(3)> will return true.
@@ -144,7 +146,7 @@ were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/SSL_get_error.pod
+13 -1
View File
@@ -25,6 +25,15 @@ other OpenSSL function calls should appear in between. The current
thread's error queue must be empty before the TLS/SSL I/O operation is
attempted, or SSL_get_error() will not work reliably.
=head1 NOTES
Some TLS implementations do not send a close_notify alert on shutdown.
On an unexpected EOF, versions before OpenSSL 3.0 returned
B<SSL_ERROR_SYSCALL>, nothing was added to the error stack, and errno was 0.
Since OpenSSL 3.0 the returned error is B<SSL_ERROR_SSL> with a meaningful
error on the error stack.
=head1 RETURN VALUES
The following return values can currently occur:
@@ -44,6 +53,9 @@ No more data can be read.
Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily
indicate that the underlying transport has been closed.
This error can also appear when the option B<SSL_OP_IGNORE_UNEXPECTED_EOF>
is set. See L<SSL_CTX_set_options(3)> for more details.
=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
The operation did not complete and can be retried later.
@@ -166,7 +178,7 @@ The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/SSL_read_early_data.pod
+6 -5
View File
@@ -58,10 +58,11 @@ SSL_set_allow_early_data_cb
These functions are used to send and receive early data where TLSv1.3 has been
negotiated. Early data can be sent by the client immediately after its initial
ClientHello without having to wait for the server to complete the handshake.
Early data can only be sent if a session has previously been established with
the server, and the server is known to support it. Additionally these functions
can be used to send data from the server to the client when the client has not
yet completed the authentication stage of the handshake.
Early data can be sent if a session has previously been established with the
server or when establishing a new session using an out-of-band PSK, and only
when the server is known to support it. Additionally these functions can be used
to send data from the server to the client when the client has not yet completed
the authentication stage of the handshake.
Early data has weaker security properties than other data sent over an SSL/TLS
connection. In particular the data does not have forward secrecy. There are also
@@ -364,7 +365,7 @@ All of the functions described above were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/SSL_shutdown.pod
+5 -3
View File
@@ -83,8 +83,10 @@ message, otherwise an unexpected EOF will be reported.
There are implementations that do not send the required close_notify alert.
If there is a need to communicate with such an implementation, and it's clear
that all data has been received, do not wait for the peer's close_notify alert.
Waiting for the close_notify alert when the peer just closes the connection will
result in an error being generated.
Waiting for the close_notify alert when the peer just closes the connection
will result in an error being generated.
The error can be ignored using the B<SSL_OP_IGNORE_UNEXPECTED_EOF>.
For more information see L<SSL_CTX_set_options(3)>.
=head2 First to close the connection
@@ -159,7 +161,7 @@ It can also occur when not all data was read using SSL_read().
L<SSL_get_error(3)>, L<SSL_connect(3)>,
L<SSL_accept(3)>, L<SSL_set_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(3)>, L<SSL_CTX_set_options(3)>
L<SSL_clear(3)>, L<SSL_free(3)>,
L<ssl(7)>, L<bio(7)>
doc/man3/X509_PUBKEY_new.pod
+15 -6
View File
@@ -5,8 +5,8 @@
X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup,
X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get,
d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param,
X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param,
X509_PUBKEY_eq - SubjectPublicKeyInfo public key functions
=head1 SYNOPSIS
@@ -17,8 +17,8 @@ X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a);
int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key);
EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
EVP_PKEY *X509_PUBKEY_get0(const X509_PUBKEY *key);
EVP_PKEY *X509_PUBKEY_get(const X509_PUBKEY *key);
EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length);
int i2d_PUBKEY(const EVP_PKEY *a, unsigned char **pp);
@@ -34,7 +34,8 @@ X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
unsigned char *penc, int penclen);
int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg,
const unsigned char **pk, int *ppklen,
X509_ALGOR **pa, X509_PUBKEY *pub);
X509_ALGOR **pa, const X509_PUBKEY *pub);
int X509_PUBKEY_eq(X509_PUBKEY *a, X509_PUBKEY *b);
=head1 DESCRIPTION
@@ -81,6 +82,8 @@ parameters is not required it can be set to B<NULL>. All of the
retrieved pointers are internal and must not be freed after the
call.
X509_PUBKEY_eq() compares two B<X509_PUBKEY> values.
=head1 NOTES
The B<X509_PUBKEY> functions can be used to encode and decode public keys
@@ -104,15 +107,21 @@ structure or B<NULL> if an error occurs.
X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param()
return 1 for success and 0 if an error occurred.
X509_PUBKEY_eq() returns 1 for equal, 0 for different, and < 0 on error.
=head1 SEE ALSO
L<d2i_X509(3)>,
L<ERR_get_error(3)>,
L<X509_get_pubkey(3)>,
=head1 HISTORY
The X509_PUBKEY_eq() function was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/X509_STORE_add_cert.pod
-2
View File
@@ -32,8 +32,6 @@ X509_STORE_load_locations
int X509_STORE_load_path(X509_STORE *ctx, const char *dir);
int X509_STORE_load_store(X509_STORE *ctx, const char *uri);
Deprecated:
int X509_STORE_load_locations(X509_STORE *ctx,
const char *file, const char *dir);
doc/man3/X509_dup.pod
+5
View File
@@ -81,7 +81,11 @@ IPAddressOrRange_free,
IPAddressOrRange_new,
IPAddressRange_free,
IPAddressRange_new,
ISSUER_SIGN_TOOL_free,
ISSUER_SIGN_TOOL_it,
ISSUER_SIGN_TOOL_new,
ISSUING_DIST_POINT_free,
ISSUING_DIST_POINT_it,
ISSUING_DIST_POINT_new,
NAME_CONSTRAINTS_free,
NAME_CONSTRAINTS_new,
@@ -252,6 +256,7 @@ TS_TST_INFO_new,
USERNOTICE_free,
USERNOTICE_new,
X509_ALGOR_free,
X509_ALGOR_it,
X509_ALGOR_new,
X509_ATTRIBUTE_dup,
X509_ATTRIBUTE_free,
doc/man3/X509_get0_distinguishing_id.pod
+3 -1
View File
@@ -21,7 +21,9 @@ The Distinguishing ID is defined in FIPS 196 as follows:
=over 4
I<Distinguishing identifier>: information which unambiguously distinguishes
=item I<Distinguishing identifier>
Information which unambiguously distinguishes
an entity in the authentication process.
=back
doc/man3/X509_load_http.pod
-63
View File
@@ -1,63 +0,0 @@
=pod
=head1 NAME
X509_load_http,
X509_http_nbio,
X509_CRL_load_http,
X509_CRL_http_nbio
- certificate and CRL loading functions
=head1 SYNOPSIS
#include <openssl/x509.h>
X509 *X509_load_http(const char *url, BIO *bio, BIO *rbio, int timeout);
X509_CRL *X509_CRL_load_http(const char *url, BIO *bio, BIO *rbio, int timeout);
#define X509_http_nbio(url)
#define X509_CRL_http_nbio(url)
=head1 DESCRIPTION
X509_load_http() and X509_CRL_load_http() loads a certificate or a CRL,
respectively, in ASN.1 format using HTTP from the given B<url>.
If B<bio> is given and B<rbio> is NULL then this BIO is used instead of an
internal one for connecting, writing the request, and reading the response.
If both B<bio> and B<rbio> are given (which may be memory BIOs, for instance)
then no explicit connection is attempted,
B<bio> is used for writing the request, and B<rbio> for reading the response.
If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
to wait until the transfer is complete.
A value of 0 enables waiting indefinitely,
while a value < 0 immediately leads to a timeout condition.
X509_http_nbio() and X509_CRL_http_nbio() are macros for backward compatibility
that have the same effect as the functions above but with infinite timeout
and without the possibility to specify custom BIOs.
=head1 RETURN VALUES
On success the function yield the loaded value, else NULL.
Error conditions include connection/transfer timeout, parse errors, etc.
=head1 SEE ALSO
L<OSSL_HTTP_get_asn1(3)>
=head1 HISTORY
X509_load_http() and X509_CRL_load_http() were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/d2i_X509.pod
+2
View File
@@ -75,6 +75,7 @@ d2i_IPAddressChoice,
d2i_IPAddressFamily,
d2i_IPAddressOrRange,
d2i_IPAddressRange,
d2i_ISSUER_SIGN_TOOL,
d2i_ISSUING_DIST_POINT,
d2i_NAMING_AUTHORITY,
d2i_NETSCAPE_CERT_SEQUENCE,
@@ -267,6 +268,7 @@ i2d_IPAddressChoice,
i2d_IPAddressFamily,
i2d_IPAddressOrRange,
i2d_IPAddressRange,
i2d_ISSUER_SIGN_TOOL,
i2d_ISSUING_DIST_POINT,
i2d_NAMING_AUTHORITY,
i2d_NETSCAPE_CERT_SEQUENCE,
doc/man5/fips_config.pod
+30 -20
View File
@@ -6,26 +6,36 @@ fips_config - OpenSSL FIPS configuration
=head1 DESCRIPTION
A separate configuration file containing data related to FIPS 'self tests' is
written to during installation time.
This data is used for 2 purposes when the fips module is loaded:
A separate configuration file, using the OpenSSL L<config(5)> syntax,
is used to hold information about the FIPS module. This includes a digest
of the shared library file, and status about the self-testing.
This data is used automatically by the module itself for two
purposes:
=over 4
=item - Verify the module's checksum each time the fips module loads.
=item - Run the startup FIPS self-test known answer tests (KATS).
=item - Run the startup FIPS self test KATS (known answer tests).
This only needs to be run once during installation.
This is done once, at installation time.
=item - Verify the module's checksum.
This is done each time the module is used.
=back
The supported options are:
This file is generated by the L<openssl-fipsinstall(1)> program, and
used internally by the FIPS module during its initialization.
The following options are supported. They should all appear in a section
whose name is identified by the B<fips> option in the B<providers>
section, as desribed in L<config(5)/Provider Configuration Module>.
=over 4
=item B<module-checksum>
=item B<module-mac>
The calculated MAC of the module file
The calculated MAC of the FIPS provider file.
=item B<install-version>
@@ -33,26 +43,26 @@ A version number for the fips install process. Should be 1.
=item B<install-status>
The install status indicator description that will be verified.
If this field is not present the FIPS self tests will run when the fips module
loads.
This value should only be written to after the FIPS module has
An indicator that the self-tests were run.
This should only be written after the module has
successfully passed its self tests during installation.
If this field is not present, then the self tests will run when the module
loads.
=item B<install-checksum>
=item B<install-mac>
The calculated MAC of the install status indicator.
It is initially empty and is written to at the same time as the install_status.
A MAC of the value of the B<install-status> option, to prevent accidental
changes to that value.
It is written-to at the same time as B<install-status> is updated.
=back
For example:
[fips_install]
install-version = 1
module-checksum = 41:D0:FA:C2:5D:41:75:CD:7D:C3:90:55:6F:A4:DC
install-checksum = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C
module-mac = 41:D0:FA:C2:5D:41:75:CD:7D:C3:90:55:6F:A4:DC
install-mac = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C
install-status = INSTALL_SELF_TEST_KATS_RUN
=head1 SEE ALSO
@@ -61,7 +71,7 @@ L<config(5)>
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man5/x509v3_config.pod
+281 -266
View File
@@ -6,112 +6,148 @@ x509v3_config - X509 V3 certificate extension configuration format
=head1 DESCRIPTION
Several of the OpenSSL utilities can add extensions to a certificate or
Several OpenSSL commands can add extensions to a certificate or
certificate request based on the contents of a configuration file.
The syntax of this file is described in L<config(5)>.
The commands typically have an option to specify the name of the configuration
file, and a section within that file; see the documentation of the
individual command for details.
Typically the application will contain an option to point to an extension
section. Each line of the extension section takes the form:
This page uses B<extensions> as the name of the section, when needed
in examples.
extension_name=[critical,] extension_options
Each entry in the extension section takes the form:
If B<critical> is present then the extension will be critical.
name = [critical, ]value(s)
The format of B<extension_options> depends on the value of B<extension_name>.
If B<critical> is present then the extension will be marked as critical.
There are four main types of extension: I<string> extensions, I<multi-valued>
extensions, I<raw> and I<arbitrary> extensions.
The format of B<values> depends on the value of B<name>, many have a
type-value pairing where the type and value are separated by a colon.
There are four main types of extension:
string
multi-valued
raw
arbitrary
Each is described in the following paragraphs.
String extensions simply have a string which contains either the value itself
or how it is obtained.
For example:
nsComment="This is a Comment"
Multi-valued extensions have a short form and a long form. The short form
is a list of names and values:
is a commma-separated list of names and values:
basicConstraints=critical,CA:true,pathlen:1
basicConstraints = critical, CA:true, pathlen:1
The long form allows the values to be placed in a separate section:
basicConstraints=critical,@bs_section
[extensions]
basicConstraints = critical, @basic_constraints
[bs_section]
CA=true
pathlen=1
[basic_constraints]
CA = true
pathlen = 1
Both forms are equivalent.
The syntax of raw extensions is governed by the extension code: it can
for example contain data in multiple sections. The correct syntax to
use is defined by the extension code itself: check out the certificate
policies extension for an example.
If an extension is multi-value and a field value must contain a comma the long
form must be used otherwise the comma would be misinterpreted as a field
separator. For example:
If an extension type is unsupported then the I<arbitrary> extension syntax
subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
will produce an error but the equivalent form:
[extensions]
subjectAltName = @subject_alt_section
[subject_alt_section]
subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
OpenSSL does not support multiple occurences of the same field within a
section. In this example:
[extensions]
subjectAltName = @alt_section
[alt_section]
email = steve@here
email = steve@there
will only recognize the last value. To specify multiple values append a
numeric identifier, as shown here:
[extensions]
subjectAltName = @alt_section
[alt_section]
email.1 = steve@here
email.2 = steve@there
The syntax of raw extensions is defined by the source code that parses
the extension but should be documened.
See L</Certificate Policies> for an example of a raw extension.
If an extension type is unsupported, then the I<arbitrary> extension syntax
must be used, see the L</ARBITRARY EXTENSIONS> section for more details.
=head1 STANDARD EXTENSIONS
The following sections describe each supported extension in detail.
The following sections describe the syntax of each supported extension.
They do not define the semantics of the extension.
=head2 Basic Constraints
This is a multi valued extension which indicates whether a certificate is
a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
This is a multi-valued extension which indicates whether a certificate is
a CA certificate. The first value is B<CA> followed by B<TRUE> or
B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a
non-negative value can be included.
For example:
basicConstraints=CA:TRUE
basicConstraints = CA:TRUE
basicConstraints=CA:FALSE
basicConstraints = CA:FALSE
basicConstraints=critical,CA:TRUE, pathlen:0
A CA certificate B<must> include the basicConstraints value with the CA field
set to TRUE. An end user certificate must either set CA to FALSE or exclude the
extension entirely. Some software may require the inclusion of basicConstraints
with CA set to FALSE for end entity certificates.
The pathlen parameter indicates the maximum number of CAs that can appear
below this one in a chain. So if you have a CA with a pathlen of zero it can
only be used to sign end user certificates and not further CAs.
basicConstraints = critical, CA:TRUE, pathlen:1
A CA certificate I<must> include the B<basicConstraints> name with the B<CA>
parameter set to B<TRUE>. An end-user certificate must either have B<CA:FALSE>
or omit the extension entirely.
The B<pathlen> parameter specifies the maximum number of CAs that can appear
below this one in a chain. A B<pathlen> of zero means the CA cannot sign
any sub-CA's, and can only sign end-entity certificates.
=head2 Key Usage
Key usage is a multi valued extension consisting of a list of names of the
permitted key usages.
The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
and decipherOnly.
Key usage is a multi-valued extension consisting of a list of names of
the permitted key usages. The defined values are: C<digitalSignature>,
C<nonRepudiation>, C<keyEncipherment>, C<dataEncipherment>, C<keyAgreement>,
C<keyCertSign>, C<cRLSign>, C<encipherOnly>, and C<decipherOnly>.
Examples:
keyUsage=digitalSignature, nonRepudiation
keyUsage=critical, keyCertSign
keyUsage = digitalSignature, nonRepudiation
keyUsage = critical, keyCertSign
=head2 Extended Key Usage
This extensions consists of a list of usages indicating purposes for which
the certificate public key can be used for,
These can either be object short names or the dotted numerical form of OIDs.
While any OID can be used only certain values make sense. In particular the
following PKIX, NS and MS values are meaningful:
This extension consists of a list of values indicating purposes for which
the certificate public key can be used for, Each value can be either a
short text name or an OID.
The following text names, and their intended meaning, are known:
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
serverAuth SSL/TLS Web Server Authentication
clientAuth SSL/TLS Web Client Authentication
codeSigning Code signing
emailProtection E-mail Protection (S/MIME)
timeStamping Trusted Timestamping
OCSPSigning OCSP Signing
ipsecIKE ipsec Internet Key Exchange
@@ -122,242 +158,267 @@ following PKIX, NS and MS values are meaningful:
Examples:
extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=serverAuth,clientAuth
extendedKeyUsage = critical, codeSigning, 1.2.3.4
extendedKeyUsage = serverAuth, clientAuth
=head2 Subject Key Identifier
This is really a string extension and can take two possible values. Either
the word B<hash> which will automatically follow the guidelines in RFC3280
or a hex string giving the extension value to include. The use of the hex
string is strongly discouraged.
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
is strongly discouraged.
Example:
subjectKeyIdentifier=hash
subjectKeyIdentifier = hash
=head2 Authority Key Identifier
The authority key identifier extension permits two options. keyid and issuer:
both can take the optional value "always".
This extension has two options, B<keyid> and B<issuer>. Either or both
can have the value B<always>, indicated by putting a colon between
the option and its value.
If the keyid option is present an attempt is made to copy the subject key
identifier from the parent certificate. If the value "always" is present
then an error is returned if the option fails.
The issuer option copies the issuer and serial number from the issuer
certificate. This will only be done if the keyid option fails or
is not included unless the "always" flag will always include the value.
Example:
authorityKeyIdentifier=keyid,issuer
=head2 Subject Alternative Name
The subject alternative name extension allows various literal values to be
included in the configuration file. These include B<email> (an email address)
B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
(a distinguished name) and otherName.
The email option include a special 'copy' value. This will automatically
include any email addresses contained in the certificate subject name in
the extension.
The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
The value of B<dirName> should point to a section containing the distinguished
name to use as a set of name value pairs. Multi values AVAs can be formed by
prefacing the name with a B<+> character.
otherName can include arbitrary data associated with an OID: the value
should be the OID followed by a semicolon and the content in standard
L<ASN1_generate_nconf(3)> format.
If B<keyid> is present, than an attempt is made to copy the subject key
identifier from the parent certificate. If the value B<always> is present,
then an error can be returned if the option fails. If B<issuer> is present,
an attempt is made to copy the issuer and serial number from the parent
certificate. This is done if the B<keyid> option fails, or if B<issuer>
has B<always> specified.
Examples:
subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
subjectAltName=IP:192.168.7.1
subjectAltName=IP:13::17
subjectAltName=email:my@other.address,RID:1.2.3.4
subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
authorityKeyIdentifier = keyid, issuer
subjectAltName=dirName:dir_sect
authorityKeyIdentifier = keyid, issuer:always
=head2 Subject Alternative Name
This is a multi-valued extension that supports several types of name
identifier, including
B<email> (an email address),
B<URI> (a uniform resource indicator),
B<DNS> (a DNS domain name),
B<RID> (a registered ID: OBJECT IDENTIFIER),
B<IP> (an IP address),
B<dirName> (a distinguished name),
and B<otherName>.
The syntax of each is described in the following paragraphs.
The B<email> option has a special C<copy> value, which will automatically
include any email addresses contained in the certificate subject name in
the extension.
The IP address used in the B<IP> option can be in either IPv4 or IPv6 format.
The value of B<dirName> is specifies the configuration section containing
the distinguished name to use, as a set of name-value pairs.
Multi-valued AVAs can be formed by prefacing the name with a B<+> character.
The value of B<otherName> can include arbitrary data associated with an OID;
the value should be the OID followed by a semicolon and the content in specified
using the syntax in L<ASN1_generate_nconf(3)>.
Examples:
subjectAltName = email:copy, email:my@other.address, URI:http://my.url.here/
subjectAltName = IP:192.168.7.1
subjectAltName = IP:13::17
subjectAltName = email:my@other.address, RID:1.2.3.4
subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
[extensions]
subjectAltName = dirName:dir_sect
[dir_sect]
C=UK
O=My Organization
OU=My Unit
CN=My Name
C = UK
O = My Organization
OU = My Unit
CN = My Name
=head2 Issuer Alternative Name
The issuer alternative name option supports all the literal options of
subject alternative name. It does B<not> support the email:copy option because
that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer
certificate (if possible).
This extension supports most of the options of subject alternative name;
it does not support B<email:copy>.
It also adds B<issuer:copy> as an allowed value, which copies any subject
alternative names from the issuer certificate, if possible.
Example:
issuerAltName = issuer:copy
=head2 Authority Info Access
The authority information access extension gives details about how to access
certain information relating to the CA. Its syntax is accessOID;location
where I<location> has the same syntax as subject alternative name (except
that email:copy is not supported). accessOID can be any valid OID but only
certain values are meaningful, for example OCSP and caIssuers.
This extension gives details about how to retrieve information that
related to the certificate that the CA makes available. The syntax is
B<access_id;location>, where B<access_id> is an object identifier
(although only a few values are well-known) and B<location> has the same
syntax as subject alternative name (except that B<email:copy> is not supported).
Example:
Examples:
authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
=head2 CRL distribution points
This is a multi-valued extension whose options can be either in name:value pair
using the same form as subject alternative name or a single value representing
a section name containing all the distribution point fields.
This is a multi-valued extension whose values can be either a name-value
pair using the same form as subject alternative name or a single value
specifying the section name containing all the distribution point values.
For a name:value pair a new DistributionPoint with the fullName field set to
the given value both the cRLissuer and reasons fields are omitted in this case.
When a name-value pair is used, a DistributionPoint extension will
be set with the given value as the fullName field as the distributionPoint
value, and the reasons and cRLIssuer fields will be omitted.
In the single option case the section indicated contains values for each
field. In this section:
When a single option is used, the value specifies the section, and that
section can have the following items:
If the name is "fullname" the value field should contain the full name
of the distribution point in the same format as subject alternative name.
=over 4
If the name is "relativename" then the value field should contain a section
name whose contents represent a DN fragment to be placed in this field.
=item fullname
The name "CRLIssuer" if present should contain a value for this field in
subject alternative name format.
The full name of the distribution point, in the same format as the subject
alternative name.
If the name is "reasons" the value field should consist of a comma
separated field containing the reasons. Valid reasons are: "keyCompromise",
"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
"certificateHold", "privilegeWithdrawn" and "AACompromise".
=item relativename
The value is taken as a distinguished name fragment that is set as the
value of the nameRelativeToCRLIssuer field.
=item CRLIssuer
The value must in the same format as the subject alternative name.
=item reasons
A multi-value field that contains the reasons for revocation. The recognized
values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
C<superseded>, C<cessationOfOperation>, C<certificateHold>,
C<privilegeWithdrawn>, and C<AACompromise>.
=back
Only one of B<fullname> or B<relativename> should be specified.
Simple examples:
crlDistributionPoints=URI:http://myhost.com/myca.crl
crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
crlDistributionPoints = URI:http://myhost.com/myca.crl
crlDistributionPoints = URI:http://my.com/my.crl, URI:http://oth.com/my.crl
Full distribution point example:
crlDistributionPoints=crldp1_section
[extensions]
crlDistributionPoints = crldp1_section
[crldp1_section]
fullname=URI:http://myhost.com/myca.crl
CRLissuer=dirName:issuer_sect
reasons=keyCompromise, CACompromise
fullname = URI:http://myhost.com/myca.crl
CRLissuer = dirName:issuer_sect
reasons = keyCompromise, CACompromise
[issuer_sect]
C=UK
O=Organisation
CN=Some Name
C = UK
O = Organisation
CN = Some Name
=head2 Issuing Distribution Point
This extension should only appear in CRLs. It is a multi valued extension
This extension should only appear in CRLs. It is a multi-valued extension
whose syntax is similar to the "section" pointed to by the CRL distribution
points extension with a few differences.
points extension. The following names have meaning:
The names "reasons" and "CRLissuer" are not recognized.
=over 4
The name "onlysomereasons" is accepted which sets this field. The value is
in the same format as the CRL distribution point "reasons" field.
=item fullname
The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
the values should be a boolean value (TRUE or FALSE) to indicate the value of
the corresponding field.
The full name of the distribution point, in the same format as the subject
alternative name.
=item relativename
The value is taken as a distinguished name fragment that is set as the
value of the nameRelativeToCRLIssuer field.
=item onlysomereasons
A multi-value field that contains the reasons for revocation. The recognized
values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
C<superseded>, C<cessationOfOperation>, C<certificateHold>,
C<privilegeWithdrawn>, and C<AACompromise>.
=item onlyuser, onlyCA, onlyAA, indirectCRL
The value for each of these names is a boolean.
=back
Example:
issuingDistributionPoint=critical, @idp_section
[extensions]
issuingDistributionPoint = critical, @idp_section
[idp_section]
fullname=URI:http://myhost.com/myca.crl
indirectCRL=TRUE
onlysomereasons=keyCompromise, CACompromise
[issuer_sect]
C=UK
O=Organisation
CN=Some Name
fullname = URI:http://myhost.com/myca.crl
indirectCRL = TRUE
onlysomereasons = keyCompromise, CACompromise
=head2 Certificate Policies
This is a I<raw> extension. All the fields of this extension can be set by
using the appropriate syntax.
This is a I<raw> extension that supports all of the defined fields of the
certificate extension.
If you follow the PKIX recommendations and just using one OID then you just
include the value of that OID. Multiple OIDs can be set separated by commas,
for example:
Policies without qualifiers are specified by giving the OID.
Multiple policies are comma-separated. For example:
certificatePolicies= 1.2.4.5, 1.1.3.4
certificatePolicies = 1.2.4.5, 1.1.3.4
If you wish to include qualifiers then the policy OID and qualifiers need to
be specified in a separate section: this is done by using the @section syntax
instead of a literal OID value.
To include policy qualifiers, use the "@section" syntax to point to a
section that specifies all the information.
The section referred to must include the policy OID using the name
policyIdentifier, cPSuri qualifiers can be included using the syntax:
B<policyIdentifier>. cPSuri qualifiers can be included using the syntax:
CPS.nnn=value
CPS.nnn = value
where C<nnn> is a number.
userNotice qualifiers can be set using the syntax:
userNotice.nnn=@notice
userNotice.nnn = @notice
The value of the userNotice qualifier is specified in the relevant section.
This section can include explicitText, organization and noticeNumbers
This section can include B<explicitText>, B<organization>, and B<noticeNumbers>
options. explicitText and organization are text strings, noticeNumbers is a
comma separated list of numbers. The organization and noticeNumbers options
(if included) must BOTH be present. If you use the userNotice option with IE5
then you need the 'ia5org' option at the top level to modify the encoding:
otherwise it will not be interpreted properly.
(if included) must BOTH be present. Some software might require
the B<ia5org> option at the top level; this changes the encoding from
Displaytext to IA5String.
Example:
certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
[extensions]
certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
[polsect]
policyIdentifier = 1.3.5.8
CPS.1="http://my.host.name/"
CPS.2="http://my.your.name/"
userNotice.1=@notice
CPS.1 = "http://my.host.name/"
CPS.2 = "http://my.your.name/"
userNotice.1 = @notice
[notice]
explicitText = "Explicit Text Here"
organization = "Organisation Name"
noticeNumbers = 1, 2, 3, 4
explicitText="Explicit Text Here"
organization="Organisation Name"
noticeNumbers=1,2,3,4
The B<ia5org> option changes the type of the I<organization> field. In RFC2459
it can only be of type DisplayText. In RFC3280 IA5String is also permissible.
Some software (for example some versions of MSIE) may require ia5org.
ASN1 type of explicitText can be specified by prepending B<UTF8>,
B<BMP> or B<VISIBLE> prefix followed by colon. For example:
The character encoding of explicitText can be specified by prefixing the
value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example:
[notice]
explicitText="UTF8:Explicit Text Here"
explicitText = "UTF8:Explicit Text Here"
=head2 Policy Constraints
@@ -369,7 +430,6 @@ Example:
policyConstraints = requireExplicitPolicy:3
=head2 Inhibit Any Policy
This is a string extension whose value must be a non negative integer.
@@ -378,33 +438,31 @@ Example:
inhibitAnyPolicy = 2
=head2 Name Constraints
The name constraints extension is a multi-valued extension. The name should
This is a multi-valued extension. The name should
begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
the name and the value follows the syntax of subjectAltName except email:copy
the name and the value follows the syntax of subjectAltName except
B<email:copy>
is not supported and the B<IP> form should consist of an IP addresses and
subnet mask separated by a B</>.
Examples:
nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
nameConstraints=permitted;email:.somedomain.com
nameConstraints=excluded;email:.com
nameConstraints = permitted;email:.somedomain.com
nameConstraints = excluded;email:.com
=head2 OCSP No Check
The OCSP No Check extension is a string extension but its value is ignored.
This is a string extension. It is parsed, but ignored.
Example:
noCheck = ignored
=head2 TLS Feature (aka Must Staple)
This is a multi-valued extension consisting of a list of TLS extension
@@ -418,7 +476,6 @@ Example:
tlsfeature = status_request
=head1 DEPRECATED EXTENSIONS
The following extensions are non standard, Netscape specific and largely
@@ -428,16 +485,10 @@ obsolete. Their use in new applications is discouraged.
Netscape Comment (B<nsComment>) is a string extension containing a comment
which will be displayed when the certificate is viewed in some browsers.
Example:
nsComment = "Some Random Comment"
Other supported extensions in this category are: B<nsBaseUrl>,
Other extensions of this type are: B<nsBaseUrl>,
B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
and B<nsSslServerName>.
=head2 Netscape Certificate Type
This is a multi-valued extensions which consists of a list of flags to be
@@ -448,7 +499,6 @@ now used instead.
Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
=head1 ARBITRARY EXTENSIONS
If an extension is not supported by the OpenSSL code then it must be encoded
@@ -462,26 +512,25 @@ The first way is to use the word ASN1 followed by the extension content
using the same syntax as L<ASN1_generate_nconf(3)>.
For example:
1.2.3.4=critical,ASN1:UTF8String:Some random data
1.2.3.4=ASN1:SEQUENCE:seq_sect
[extensions]
1.2.3.4 = critical, ASN1:UTF8String:Some random data
1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
[seq_sect]
field1 = UTF8:field1
field2 = UTF8:field2
It is also possible to use the word DER to include the raw encoded data in any
extension.
1.2.3.4=critical,DER:01:02:03:04
1.2.3.4=DER:01020304
1.2.3.4 = critical, DER:01:02:03:04
1.2.3.4.1 = DER:01020304
The value following DER is a hex dump of the DER encoding of the extension
Any extension can be placed in this form to override the default behaviour.
For example:
basicConstraints=critical,DER:00:01:02:03
basicConstraints = critical, DER:00:01:02:03
=head1 WARNINGS
@@ -491,41 +540,7 @@ purposes prohibited by their extensions because a specific application does
not recognize or honour the values of the relevant extensions.
The DER and ASN1 options should be used with caution. It is possible to create
totally invalid extensions if they are not used carefully.
=head1 NOTES
If an extension is multi-value and a field value must contain a comma the long
form must be used otherwise the comma would be misinterpreted as a field
separator. For example:
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
will produce an error but the equivalent form:
subjectAltName=@subject_alt_section
[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
Due to the behaviour of the OpenSSL B<conf> library the same field name
can only occur once in a section. This means that:
subjectAltName=@alt_section
[alt_section]
email=steve@here
email=steve@there
will only recognize the last value. This can be worked around by using the form:
[alt_section]
email.1=steve@here
email.2=steve@there
invalid extensions if they are not used carefully.
=head1 SEE ALSO
doc/man7/EVP_KDF-HKDF.pod
+8 -8
View File
@@ -87,7 +87,7 @@ an error will occur.
A context for HKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an HKDF expand operation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function. When using
@@ -107,7 +107,7 @@ salt value "salt" and info value "label":
OSSL_PARAM params[5], *p = params;
kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -119,14 +119,14 @@ salt value "salt" and info value "label":
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -135,10 +135,10 @@ RFC 5869
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-KB.pod
+10 -10
View File
@@ -57,7 +57,7 @@ Depending on whether mac is CMAC or HMAC, either digest or cipher is required
A context for KBKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an KBKDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -76,7 +76,7 @@ Label "label", and Context "context".
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -90,12 +90,12 @@ Label "label", and Context "context".
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"context", strlen("context"));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
else if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret",
Label "label", and IV "sixteen bytes iv".
@@ -107,7 +107,7 @@ Label "label", and IV "sixteen bytes iv".
unsigned char *iv = "sixteen bytes iv";
kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
@@ -122,12 +122,12 @@ Label "label", and IV "sixteen bytes iv".
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
iv, strlen(iv));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
else if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -136,7 +136,7 @@ NIST SP800-108, IETF RFC 6803, IETF RFC 8009.
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-KRB5KDF.pod
+4 -4
View File
@@ -44,7 +44,7 @@ If a value is already set, the contents are replaced.
A context for KRB5KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
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
@@ -70,7 +70,7 @@ This example derives a key using the AES-128-CBC cipher:
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER,
@@ -87,7 +87,7 @@ This example derives a key using the AES-128-CBC cipher:
if (EVP_KDF_derive(kctx, out, outlen) <= 0)
/* Error */
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -96,7 +96,7 @@ RFC 3961
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
doc/man7/EVP_KDF-PBKDF2.pod
+3 -3
View File
@@ -82,9 +82,9 @@ SP800-132
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SCRYPT.pod
+8 -8
View File
@@ -66,7 +66,7 @@ Both r and p are parameters of type B<uint32_t>.
A context for scrypt can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an scrypt key derivation is specified via the
"keylen" parameter to the L<EVP_KDF_derive(3)> function.
@@ -82,7 +82,7 @@ This example derives a 64-byte long test vector using scrypt with the password
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
@@ -93,8 +93,8 @@ This example derives a 64-byte long test vector using scrypt with the password
*p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
*p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
@@ -115,7 +115,7 @@ This example derives a 64-byte long test vector using scrypt with the password
assert(!memcmp(out, expected, sizeof(out)));
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -124,9 +124,9 @@ RFC 7914
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SS.pod
+16 -16
View File
@@ -66,7 +66,7 @@ This parameter sets an optional value for fixedinfo, also known as otherinfo.
A context for SSKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an SSKDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -82,7 +82,7 @@ and fixedinfo value "label":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -92,14 +92,14 @@ and fixedinfo value "label":
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
fixedinfo value "label" and salt "salt":
@@ -110,7 +110,7 @@ fixedinfo value "label" and salt "salt":
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
@@ -124,14 +124,14 @@ fixedinfo value "label" and salt "salt":
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
"salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
@@ -142,7 +142,7 @@ fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
OSSL_PARAM params[7], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
@@ -157,14 +157,14 @@ fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
"salt", (size_t)4);
*p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -173,9 +173,9 @@ NIST SP800-56Cr1.
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-SSHKDF.pod
+6 -6
View File
@@ -87,7 +87,7 @@ A single char of value 70 (ASCII char 'F').
A context for SSHKDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of the SSHKDF derivation is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -111,7 +111,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
OSSL_PARAM params[6], *p = params;
kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -125,7 +125,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
*p++ = OSSL_PARAM_construct_int(OSSL_KDF_PARAM_SSHKDF_TYPE,
EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
/* Error */
if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
@@ -139,9 +139,9 @@ RFC 4253
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-TLS1_PRF.pod
+8 -8
View File
@@ -51,7 +51,7 @@ this should be more than enough for any normal use of the TLS PRF.
A context for the TLS PRF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The digest, secret value and seed must be set before a key is derived otherwise
an error will occur.
@@ -70,7 +70,7 @@ and seed value "seed":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -80,13 +80,13 @@ and seed value "seed":
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
"seed", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -95,9 +95,9 @@ RFC 2246, RFC 5246 and NIST SP 800-135 r1
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-X942.pod
+9 -9
View File
@@ -49,7 +49,7 @@ This parameter sets the CEK wrapping algorithm name.
A context for X942KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an X942KDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -71,9 +71,9 @@ keying material:
kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
if (kctx == NULL)
error("EVP_KDF_fetch");
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
if (kctx == NULL)
error("EVP_KDF_CTX_new");
error("EVP_KDF_new_ctx");
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -85,12 +85,12 @@ keying material:
SN_id_smime_alg_CMS3DESwrap,
strlen(SN_id_smime_alg_CMS3DESwrap));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0)
error("EVP_KDF_set_ctx_params");
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -99,9 +99,9 @@ RFC 2631
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KDF-X963.pod
+8 -8
View File
@@ -46,7 +46,7 @@ X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
A context for X963KDF can be obtained by calling:
EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf);
The output length of an X963KDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
@@ -62,7 +62,7 @@ value "label":
OSSL_PARAM params[4], *p = params;
kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
kctx = EVP_KDF_new_ctx(kdf);
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
@@ -72,14 +72,14 @@ value "label":
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
"label", (size_t)5);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
error("EVP_KDF_CTX_set_params");
if (EVP_KDF_set_ctx_params(kctx, params) <= 0) {
error("EVP_KDF_set_ctx_params");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}
EVP_KDF_CTX_free(kctx);
EVP_KDF_free_ctx(kctx);
=head1 CONFORMING TO
@@ -88,9 +88,9 @@ value "label":
=head1 SEE ALSO
L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_new_ctx(3)>,
L<EVP_KDF_free_ctx(3)>,
L<EVP_KDF_set_ctx_params(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>
doc/man7/EVP_KEYEXCH-DH.pod
+98
View File
@@ -0,0 +1,98 @@
=pod
=head1 NAME
EVP_KEYEXCH-DH
- DH Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<DH> key type.
=head2 DH key exchange parameters
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
See L<provider-keyexch(7)/Common Key Exchange parameters>.
=back
=head1 EXAMPLES
The examples assume a host and peer both generate keys using the same
named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>.
Both the host and peer transfer their public key to each other.
To convert the peer's generated key pair to a public key in DER format in order
to transfer to the host:
EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
unsigned char *peer_pub_der = NULL;
int peer_pub_der_len;
peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
...
OPENSSL_free(peer_pub_der);
To convert the received peer's public key from DER format on the host:
const unsigned char *pd = peer_pub_der;
EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
...
EVP_PKEY_free(peer_pub_key);
To derive a shared secret on the host using the host's key and the peer's public
key:
/* It is assumed that the host_key and peer_pub_key are set up */
void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
{
unsigned int pad = 1;
OSSL_PARAM params[2];
unsigned char *secret = NULL;
size_t secret_len = 0;
EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
EVP_PKEY_derive_init(dctx);
/* Optionally set the padding */
params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
params[1] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(dctx, params);
EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
/* Get the size by passing NULL as the buffer */
EVP_PKEY_derive(dctx, NULL, &secret_len);
secret = OPENSSL_zalloc(secret_len);
EVP_PKEY_derive(dctx, secret, &secret_len);
...
OPENSSL_clear_free(secret, secret_len);
EVP_PKEY_CTX_free(dctx);
}
Very similar code can be used by the peer to derive the same shared secret
using the host's public key and the peer's generated key pair.
=head1 SEE ALSO
L<EVP_PKEY-DH(7)>,
L<EVP_PKEY-FFC(7)>,
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_KEYEXCH-ECDH.pod
+133
View File
@@ -0,0 +1,133 @@
=pod
=head1 NAME
EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<ECDH> key type.
=head2 ECDH Key Exchange parameters
=over 4
=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
Sets or gets the ECDH mode of operation for the associated key exchange ctx.
In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
can be used to select between the plain Diffie-Hellman (DH) or Cofactor
Diffie-Hellman (CDH) variants of the key exchange algorithm.
When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
on, off, or resetting it to the default for the private key associated with the
given key exchange ctx.
When getting, the value should be either 1 or 0, respectively signaling if the
cofactor mode is on or off.
See also L<provider-keymgmt(7)> for the related
B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
per-key basis.
=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
Sets or gets the Key Derivation Function type to apply within the associated key
exchange ctx.
=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Derivation Function associated with the given key
exchange ctx.
=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
Sets or gets the desired size for the output of the chosen Key Derivation Function
associated with the given key exchange ctx.
=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
Sets the User Key Material to be used as part of the selected Key Derivation
Function associated with the given key exchange ctx.
=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
Gets a pointer to the User Key Material to be used as part of the selected
Key Derivation Function associated with the given key exchange ctx.
=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
Gets the size of the User Key Material to be used as part of the selected
Key Derivation Function associated with the given key exchange ctx.
=back
=head1 EXAMPLES
Keys for the host and peer must be generated as shown in
L<EVP_PKEY-EC(7)/Examples> using the same curve name.
The code to generate a shared secret for the normal case is identical to
L<EVP_KEYEXCH-DH(7)/Examples>.
To derive a shared secret on the host using the host's key and the peer's public
key but also using X963KDF with a user key material:
/* It is assumed that the host_key, peer_pub_key and ukm are set up */
void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
unsigned char *ukm, size_t ukm_len)
{
unsigned char secret[64];
size_t out_len = sizeof(secret);
size_t secret_len = out_len;
unsigned int pad = 1;
OSSL_PARAM params[6];
EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
EVP_PKEY_derive_init(dctx);
params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
"X963KDF", 0);
params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
"SHA1", 0);
params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
&out_len);
params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
ukm, ukm_len);
params[5] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(dctx, params);
EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
EVP_PKEY_derive(dctx, secret, &secret_len);
...
OPENSSL_clear_free(secret, secret_len);
EVP_PKEY_CTX_free(dctx);
}
=head1 SEE ALSO
L<EVP_PKEY-EC(7)>
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_KEYEXCH-X25519.pod
+50
View File
@@ -0,0 +1,50 @@
=pod
=head1 NAME
EVP_KEYEXCH-X25519,
EVP_KEYEXCH-X448
- X25519 and X448 Key Exchange algorithm support
=head1 DESCRIPTION
Key exchange support for the B<X25519> and B<X448> key types.
=head2 Key exchange parameters
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
See L<provider-keyexch(7)/Common Key Exchange parameters>.
=back
=head1 EXAMPLES
Keys for the host and peer can be generated as shown in
L<EVP_PKEY-X25519(7)/Examples>.
The code to generate a shared secret is identical to
L<EVP_KEYEXCH-DH(7)/Examples>.
=head1 SEE ALSO
L<EVP_PKEY-FFC(7)>,
L<EVP_PKEY-DH(7)>
L<EVP_PKEY(3)>,
L<provider-keyexch(7)>,
L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>,
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_MAC-BLAKE2.pod
+3 -3
View File
@@ -27,9 +27,9 @@ properties, to be used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -61,7 +61,7 @@ It is 32 and 64 respectively by default.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 HISTORY
doc/man7/EVP_MAC-CMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -37,7 +37,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -50,7 +50,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-GMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -39,7 +39,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -52,7 +52,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-HMAC.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -41,7 +41,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
The "flags" parameter is passed directly to HMAC_CTX_set_flags().
The following parameter can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -54,7 +54,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>, L<HMAC(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-KMAC.pod
+3 -3
View File
@@ -27,9 +27,9 @@ properties, to be used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -50,7 +50,7 @@ the input stream is set to zero.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-Poly1305.pod
+3 -3
View File
@@ -24,7 +24,7 @@ used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
The following parameter can be set with EVP_MAC_CTX_set_params():
The following parameter can be set with EVP_MAC_set_ctx_params():
=over 4
@@ -33,7 +33,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=back
The following parameters can be retrieved with
EVP_MAC_CTX_get_params():
EVP_MAC_get_ctx_params():
=over 4
@@ -46,7 +46,7 @@ The length of the "size" parameter should not exceed that of an B<unsigned int>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MAC-Siphash.pod
+3 -3
View File
@@ -25,9 +25,9 @@ used with EVP_MAC_fetch():
The general description of these parameters can be found in
L<EVP_MAC(3)/PARAMETERS>.
All these parameters can be set with EVP_MAC_CTX_set_params().
All these parameters can be set with EVP_MAC_set_ctx_params().
Furthermore, the "size" parameter can be retrieved with
EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
EVP_MAC_get_ctx_params(), or with EVP_MAC_size().
The length of the "size" parameter should not exceed that of a B<size_t>.
=over 4
@@ -40,7 +40,7 @@ The length of the "size" parameter should not exceed that of a B<size_t>.
=head1 SEE ALSO
L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
L<EVP_MAC_get_ctx_params(3)>, L<EVP_MAC_set_ctx_params(3)>,
L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
=head1 COPYRIGHT
doc/man7/EVP_MD-common.pod
+2 -7
View File
@@ -7,11 +7,8 @@ EVP_MD-common - The OpenSSL EVP_MD implementations, common things
=head1 DESCRIPTION
All the OpenSSL EVP_MD implementations understand the following
L<OSSL_PARAM(3)> entries:
=over 4
Gettable with L<EVP_MD_get_params(3)>:
L<OSSL_PARAM(3)> entries that are
gettable with L<EVP_MD_get_params(3)>, as well as these:
=over 4
@@ -49,8 +46,6 @@ This value can also be retrieved with L<EVP_MD_flags(3)>.
=back
=back
=head1 SEE ALSO
L<EVP_MD_get_params(3)>, L<provider-digest(7)>
doc/man7/EVP_PKEY-DH.pod
+234
View File
@@ -0,0 +1,234 @@
=pod
=head1 NAME
EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support
=head1 DESCRIPTION
For B<DH> FFC key agreement, two classes of domain parameters can be used:
"safe" domain parameters that are associated with approved named safe-prime
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
parameters should only be used for backward compatibility with existing
applications that cannot be upgraded to use the approved safe-prime groups.
See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
For B<DH> that is not a named group) the FIPS186-4 standard specifies that the
values used for FFC parameter generation are also required for parameter
validation. This means that optional FFC domain parameter values for
I<seed>, I<pcounter> and I<gindex> may need to be stored for validation purposes.
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
(but the I<gindex> is not).
=head2 DH parameters
In addition to the common FCC parameters that all FFC keytypes should support
(see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype
implementation supports the following:
=over 4
=item "group" (B<OSSL_PKEY_PARAM_DH_GROUP>) <UTF8 string>
Set or gets a string that associates a B<DH> named safe prime group with known
values for I<p>, I<q> and I<g>.
The following values can be used by the OpenSSL's default and FIPS providers:
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
The following additional values can also be used by OpenSSL's default provider:
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
DH named groups can be easily validated since the parameters are well known.
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
retrieved.
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer>
Used for DH generation of safe primes using the old generator code.
It is recommended to use a named safe prime group instead, if domain parameter
validation is required. The default value is 2.
These are not named safe prime groups so setting this value for the OpenSSL FIPS
provider will instead choose a named safe prime group based on the size of I<p>.
=item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
Used for getting and setting the encoding of the DH public key used in a key
exchange message for the TLS protocol.
=back
=head2 DH domain parameter / key generation parameters
In addition to the common FCC key generation parameters that all FFC key types
should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the
B<DH> keytype implementation supports the following:
=over 4
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
Sets the type of parameter generation. For B<DH> valid values are:
=over 4
=item "fips186_4"
=item "default"
=item "fips186_2"
These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
=item "group"
This specifies that a named safe prime name will be chosen using the "pbits"
type.
=item "generator"
A safe prime generator. See the "safeprime-generator" type above.
=back
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'p'.
For "fips186_4" this must be 2048.
For "fips186_2" this must be 1024.
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
=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
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.
=back
=head1 EXAMPLES
An B<EVP_PKEY> context can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
An B<DH> key can be generated with a named safe prime group by calling:
int priv_len = 2 * 112;
OSSL_PARAM params[3];
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
/* "priv_len" is optional */
params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_keygen_init(pctx);
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_gen(pctx, &pkey);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(pctx);
Legacy B<DH> domain parameters can be generated by calling:
unsigned int pbits = 2048;
unsigned int qbits = 256;
int gindex = 1;
OSSL_PARAM params[5];
EVP_PKEY *param_key = NULL;
EVP_PKEY_CTX *pctx = NULL;
pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
EVP_PKEY_paramgen_init(pctx);
params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
params[4] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_gen(pctx, &param_key);
EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
...
EVP_PKEY_free(param_key);
EVP_PKEY_CTX_free(pctx);
An B<DH> key can be generated using domain parameters by calling:
EVP_PKEY *key = NULL;
EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
EVP_PKEY_keygen_init(gctx);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);
=for comment TODO(3.0): To validate domain parameters, additional values used
during generation may be required to be set into the key.
=head1 CONFORMING TO
=over 4
=item RFC 7919 (TLS ffdhe named safe prime groups)
=item RFC 3526 (IKE modp named safe prime groups)
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
and "dh_2048_256").
=back
The following sections of SP800-56Ar3:
=over 4
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
=item Appendix D: FFC Safe-prime Groups
=back
The following sections of FIPS 186-4:
=over 4
=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
=item A.2.3 Generation of canonical generator g.
=item A.2.1 Unverifiable Generation of the Generator g.
=back
=head1 SEE ALSO
L<EVP_PKEY-FFC(7)>,
L<EVP_KEYEXCH-DH(7)>
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEYMGMT(3)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man7/EVP_PKEY-DSA.pod
+50 -209
View File
@@ -2,240 +2,77 @@
=head1 NAME
EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
- EVP_PKEY DSA and DH keytype and algorithm support
EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
=head1 DESCRIPTION
The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
providers.
The implementations support the basic DSA and DH keys, containing the public
and private keys I<pub> and I<priv> as well as the three main domain parameters
I<p>, I<q> and I<g>.
Finite field cryptography (FFC) is a method of implementing discrete logarithm
cryptography using finite field mathematics. DSA is an example of FFC and
Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
implemented as FFC.
For B<DH> FFC key agreement, two classes of domain parameters can be used:
"safe" domain parameters that are associated with approved named safe-prime
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
parameters should only be used for backward compatibility with existing
applications that cannot be upgraded to use the approved safe-prime groups.
For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard
specifies that the values used for FFC parameter generation are also required
for parameter validation.
For B<DSA> the FIPS186-4 standard specifies that the values used for FFC
parameter generation are also required for parameter validation.
This means that optional FFC domain parameter values for I<seed>, I<pcounter>
and I<gindex> may need to be stored for validation purposes.
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
(but the I<gindex> is not). For B<DSA> however, these fields are not stored in
the ASN1 data so they need to be stored externally if validation is required.
and I<gindex> may need to be stored for validation purposes. For B<DSA> these
fields are not stored in the ASN1 data so they need to be stored externally if
validation is required.
=head2 Common DH parameters
=head2 DSA parameters
=over 4
The B<DSA> key type supports the FFC parameters (see
L<EVP_PKEY-FFC(7)/FFC parameters>).
=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
=head2 DSA key generation parameters
A string that associates a B<DH> named safe prime group with known values for
I<p>, I<q> and I<g>.
The B<DSA> key type supports the FFC key generation parameters (see
L<EVP_PKEY-FFC(7)/FFC key generation parameters>
The following values can be used by the default and OpenSSL's FIPS providers:
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
The following restrictions apply to the "pbits" field:
The following additional values can also be used by the default provider:
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
DH named groups can be easily validated since the parameters are well known.
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
retrieved.
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
Used for DH generation of safe primes using the old generator code.
It is recommended to use a named safe prime group instead, if domain parameter
validation is required. The default value is 2.
These are not named safe prime groups so setting this value for the OpenSSL FIPS
provider will instead choose a named safe prime group based on the size of I<p>.
=back
=head2 Common DSA & DH parameters
In addition to the common parameters that all keytypes should support (see
L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
implementations support the following.
=over 4
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
The public key value.
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
The private key value.
=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
A DSA or Diffie-Hellman prime "p" value.
=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
A DSA or Diffie-Hellman prime "q" value.
=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
A DSA or Diffie-Hellman generator "g" value.
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
An optional domain parameter I<seed> value used during generation and validation
of I<p>, I<q> and canonical I<g>.
For validation this needs to set the I<seed> that was produced during generation.
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
Sets the index to use for canonical generation and verification of the generator
I<g>.
Set this to a positive value from 0..FF to use this mode. This I<gindex> can
then be reused during key validation to verify the value of I<g>. If this value
is not set or is -1 then unverifiable generation of the generator I<g> will be
used.
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
An optional domain parameter I<counter> value that is output during generation
of I<p>. This value must be saved if domain parameter validation is required.
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
For unverifiable generation of the generator I<g> this value is output during
generation of I<g>. Its value is the first integer larger than one that
satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
An optional informational cofactor parameter that should equal (p - 1) / q.
=back
=head2 DSA / DH key generation (FFC) parameters
The following Key Generation types are available for the built-in FFC algorithms:
=over 4
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
Sets the type of parameter generation. For DH Valid values are:
=over 4
=item "fips186_4"
The current standard. This is the default value.
=item "default"
This is an alias to use the latest implemented standard.
It is currently set to "fips186_4".
=item "group"
This specifies that a named safe prime name will be chosen using the "pbits"
type.
=item "fips186_2"
The old standard that should only be used for legacy purposes.
=item "generator"
A safe prime generator. See the "safeprime-generator" type.
=back
For DSA valid values are one of "default", "fips186_4" or "fips186_2" as
described above.
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
Sets the size (in bits) of the prime 'p'.
For "fips186_4" this must be 2048 for DH, and either of 2048 or 3072 for DSA.
For "fips186_4" this must be either 2048 or 3072.
For "fips186_2" this must be 1024.
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
=head1 EXAMPLES
Sets the size (in bits) of the prime 'q'.
An B<EVP_PKEY> context can be obtained by calling:
For "fips186_4" this can be either 224 or 256.
For "fips186_2" this has a size of 160.
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string>
An B<DH> domain parameters key can be generated by calling:
Sets the Digest algorithm to be used as part of the Key Generation Function
associated with the given Key Generation I<ctx>.
This must also be set for key validation.
unsigned int pbits = 2048;
unsigned int qbits = 256;
int gindex = 1;
OSSL_PARAM params[5];
EVP_PKEY *param_key = NULL;
EVP_PKEY_CTX *pctx = NULL;
=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
EVP_PKEY_paramgen_init(pctx);
Sets properties to be used upon look up of the implementation for the selected
Digest algorithm for the Key Generation Function associated with the given key
generation I<ctx>. This may also be set for key validation.
params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
params[4] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
EVP_PKEY_gen(pctx, &param_key);
EVP_PKEY_CTX_free(pctx);
For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
instead of generating a random seed internally. This should be used for
testing purposes only. This will either produce fixed values for the generated
parameters OR it will fail if the seed did not generate valid primes.
EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
An B<DSA> key can be generated using domain parameters by calling:
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
EVP_PKEY *key = NULL;
EVP_PKEY_CTX *gctx = NULL;
=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
These types are described above.
=back
gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
EVP_PKEY_keygen_init(gctx);
EVP_PKEY_gen(gctx, &key);
EVP_PKEY_CTX_free(gctx);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
=head1 CONFORMING TO
=over 4
=item RFC 7919 (TLS ffdhe named safe prime groups)
=item RFC 3526 (IKE modp named safe prime groups)
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
and "dh_2048_256").
=back
The following sections of SP800-56Ar3:
=over 4
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
=item Appendix D: FFC Safe-prime Groups
=back
The following sections of FIPS 186-4:
=over 4
@@ -250,9 +87,13 @@ The following sections of FIPS 186-4:
=head1 SEE ALSO
L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
L<EVP_SIGNATURE-DSA(7)>, L<EVP_KEYEXCH-DH(7)>
L<EVP_PKEY-FFC(7)>,
L<EVP_SIGNATURE-DSA(7)>
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEYMGMT(3)>,
L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-FIPS(7)>
=head1 COPYRIGHT

Some files were not shown because too many files have changed in this diff Show More