OpenSSL 1.1.1-pre2
This commit is contained in:
Hakase
@@ -0,0 +1,67 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Ed25519 - EVP_PKEY Ed25519 support
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<Ed25519> EVP_PKEY implementation supports key generation, one shot
|
||||
digest sign and digest verify using PureEdDSA and B<Ed25519> (see RFC8032).
|
||||
It has associated private and public key formats compatible with
|
||||
draft-ietf-curdle-pkix-04.
|
||||
|
||||
No additional parameters can be set during key generation one shot signing or
|
||||
verification. In particular, because PureEdDSA is used, when signing or
|
||||
verifying a digest must B<NOT> be specified.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The PureEdDSA algorithm does not support the streaming mechanism
|
||||
of other signature algorithms using, for example, EVP_DigestUpdate().
|
||||
The message to sign or verify must be passed using the one shot
|
||||
EVP_DigestSign() asn EVP_DigestVerify() functions.
|
||||
|
||||
When calling EVP_DigestSignInit() or EVP_DigestSignUpdate() the
|
||||
digest parameter B<MUST> be set to B<NULL>.
|
||||
|
||||
Applications wishing to sign certificates (or other structures such as
|
||||
CRLs or certificate requests) using Ed25519 can either use X509_sign()
|
||||
or X509_sign_ctx() in the usual way.
|
||||
|
||||
A context for the B<Ed25519> algorithm can be obtained by calling:
|
||||
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
This example generates an B<ED25519> private key and writes it to standard
|
||||
output in PEM format:
|
||||
|
||||
#include <openssl/evp.h>
|
||||
#include <openssl/pem.h>
|
||||
...
|
||||
EVP_PKEY *pkey = NULL;
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
|
||||
EVP_PKEY_keygen_init(pctx);
|
||||
EVP_PKEY_keygen(pctx, &pkey);
|
||||
EVP_PKEY_CTX_free(pctx);
|
||||
PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_CTX_new(3)>,
|
||||
L<EVP_PKEY_keygen(3)>,
|
||||
L<EVP_DigestSignInit(3)>,
|
||||
L<EVP_DigestVerifyInit(3)>,
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,111 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
RSA-PSS - EVP_PKEY RSA-PSS algorithm support
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rsa.h>
|
||||
|
||||
int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,
|
||||
const EVP_MD *md);
|
||||
int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
|
||||
const EVP_MD *md);
|
||||
int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,
|
||||
int saltlen);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<RSA-PSS> EVP_PKEY implementation is a restricted version of the RSA
|
||||
algorithm which only supports signing, verification and key generation
|
||||
using PSS padding modes with optional parameter restrictions.
|
||||
|
||||
It has associated private key and public key formats.
|
||||
|
||||
This algorithm shares several control operations with the B<RSA> algorithm
|
||||
but with some restrictions described below.
|
||||
|
||||
=head1 SIGNING AND VERIFICATION
|
||||
|
||||
Signing and verification is similar to the B<RSA> algorithm except the
|
||||
padding mode is always PSS. If the key in use has parameter restrictions then
|
||||
the corresponding signature parameters are set to the restrictions:
|
||||
for example, if the key can only be used with digest SHA256, MGF1 SHA256
|
||||
and minimum salt length 32 then the digest, MGF1 digest and salt length
|
||||
will be set to SHA256, SHA256 and 32 respectively.
|
||||
|
||||
The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
|
||||
returned if an attempt is made to set the padding mode to anything other
|
||||
than B<PSS>. It is otherwise similar to the B<RSA> version.
|
||||
|
||||
The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
|
||||
If the key has usage restrictions then an error is returned if an attempt is
|
||||
made to set the salt length below the minimum value. It is otherwise similar
|
||||
to the B<RSA> operation except detection of the salt length (using
|
||||
RSA_PSS_SALTLEN_AUTO is not supported for verification if the key has
|
||||
usage restrictions.
|
||||
|
||||
The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
|
||||
are used to set the digest and MGF1 algorithms respectively. If the key has
|
||||
usage restrictions then an error is returned if an attempt is made to set the
|
||||
digest to anything other than the restricted value. Otherwise these are
|
||||
similar to the B<RSA> versions.
|
||||
|
||||
=head1 KEY GENERATION
|
||||
|
||||
As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
|
||||
and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS:
|
||||
they have exactly the same meaning as for the RSA algorithm.
|
||||
|
||||
Optional parameter restrictions can be specified when generating a PSS key. By
|
||||
default no parameter restrictions are placed on the generated key. If any
|
||||
restrictions are set (using the macros described below) then B<all> parameters
|
||||
are restricted. For example, setting a minimum salt length also restricts the
|
||||
digest and MGF1 algorithms. If any restrictions are in place then they are
|
||||
reflected in the corresponding parameters of the public key when (for example)
|
||||
a certificate request is signed.
|
||||
|
||||
EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
|
||||
generated key can use to B<md>.
|
||||
|
||||
EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the
|
||||
generated key can use to B<md>.
|
||||
|
||||
EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length
|
||||
to B<saltlen>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for the B<RSA-PSS> algorithm can be obtained by calling:
|
||||
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);
|
||||
|
||||
The public key format is documented in RFC4055.
|
||||
|
||||
The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
|
||||
format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
|
||||
present, restricts the key parameters in the same way as the public key.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All these functions return 1 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_CTX_ctrl_str(3)>,
|
||||
L<EVP_PKEY_derive(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,58 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
X25519 - EVP_PKEY X25519 support
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<X25519> EVP_PKEY implementation supports key generation and key
|
||||
derivation using B<X25519>. It has associated private and public key formats
|
||||
compatible with draft-ietf-curdle-pkix-03.
|
||||
|
||||
No additional parameters can be set during key generation.
|
||||
|
||||
The peer public key must be set using EVP_PKEY_derive_set_peer() when
|
||||
performing key derivation.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for the B<X25519> algorithm can be obtained by calling:
|
||||
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
This example generates an B<X25519> private key and writes it to standard
|
||||
output in PEM format:
|
||||
|
||||
#include <openssl/evp.h>
|
||||
#include <openssl/pem.h>
|
||||
...
|
||||
EVP_PKEY *pkey = NULL;
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
|
||||
EVP_PKEY_keygen_init(pctx);
|
||||
EVP_PKEY_keygen(pctx, &pkey);
|
||||
EVP_PKEY_CTX_free(pctx);
|
||||
PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
|
||||
|
||||
The key derivation example in L<EVP_PKEY_derive(3)> can be used with
|
||||
B<X25519>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_CTX_new(3)>,
|
||||
L<EVP_PKEY_keygen(3)>,
|
||||
L<EVP_PKEY_derive(3)>,
|
||||
L<EVP_PKEY_derive_set_peer(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,87 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
bio - Basic I/O abstraction
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
A BIO is an I/O abstraction, it hides many of the underlying I/O
|
||||
details from an application. If an application uses a BIO for its
|
||||
I/O it can transparently handle SSL connections, unencrypted network
|
||||
connections and file I/O.
|
||||
|
||||
There are two type of BIO, a source/sink BIO and a filter BIO.
|
||||
|
||||
As its name implies a source/sink BIO is a source and/or sink of data,
|
||||
examples include a socket BIO and a file BIO.
|
||||
|
||||
A filter BIO takes data from one BIO and passes it through to
|
||||
another, or the application. The data may be left unmodified (for
|
||||
example a message digest BIO) or translated (for example an
|
||||
encryption BIO). The effect of a filter BIO may change according
|
||||
to the I/O operation it is performing: for example an encryption
|
||||
BIO will encrypt data if it is being written to and decrypt data
|
||||
if it is being read from.
|
||||
|
||||
BIOs can be joined together to form a chain (a single BIO is a chain
|
||||
with one component). A chain normally consist of one source/sink
|
||||
BIO and one or more filter BIOs. Data read from or written to the
|
||||
first BIO then traverses the chain to the end (normally a source/sink
|
||||
BIO).
|
||||
|
||||
|
||||
Some BIOs (such as memory BIOs) can be used immediately after calling
|
||||
BIO_new(). Others (such as file BIOs) need some additional initialization,
|
||||
and frequently a utility function exists to create and initialize such BIOs.
|
||||
|
||||
If BIO_free() is called on a BIO chain it will only free one BIO resulting
|
||||
in a memory leak.
|
||||
|
||||
Calling BIO_free_all() on a single BIO has the same effect as calling
|
||||
BIO_free() on it other than the discarded return value.
|
||||
|
||||
Normally the B<type> argument is supplied by a function which returns a
|
||||
pointer to a BIO_METHOD. There is a naming convention for such functions:
|
||||
a source/sink BIO is normally called BIO_s_*() and a filter BIO
|
||||
BIO_f_*();
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
Create a memory BIO:
|
||||
|
||||
BIO *mem = BIO_new(BIO_s_mem());
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_ctrl(3)>,
|
||||
L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>,
|
||||
L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
|
||||
L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
|
||||
L<BIO_find_type(3)>, L<BIO_new(3)>,
|
||||
L<BIO_new_bio_pair(3)>,
|
||||
L<BIO_push(3)>, L<BIO_read_ex(3)>,
|
||||
L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
|
||||
L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
|
||||
L<BIO_s_file(3)>, L<BIO_s_mem(3)>,
|
||||
L<BIO_s_null(3)>, L<BIO_s_socket(3)>,
|
||||
L<BIO_set_callback(3)>,
|
||||
L<BIO_should_retry(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
crypto - OpenSSL cryptographic library
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
See the individual manual pages for details.
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The OpenSSL B<crypto> library implements a wide range of cryptographic
|
||||
algorithms used in various Internet standards. The services provided
|
||||
by this library are used by the OpenSSL implementations of SSL, TLS
|
||||
and S/MIME, and they have also been used to implement SSH, OpenPGP, and
|
||||
other cryptographic standards.
|
||||
|
||||
B<libcrypto> consists of a number of sub-libraries that implement the
|
||||
individual algorithms.
|
||||
|
||||
The functionality includes symmetric encryption, public key
|
||||
cryptography and key agreement, certificate handling, cryptographic
|
||||
hash functions, cryptographic pseudo-random number generator, and
|
||||
various utilities.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Some of the newer functions follow a naming convention using the numbers
|
||||
B<0> and B<1>. For example the functions:
|
||||
|
||||
int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
|
||||
int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
|
||||
|
||||
The B<0> version uses the supplied structure pointer directly
|
||||
in the parent and it will be freed up when the parent is freed.
|
||||
In the above example B<crl> would be freed but B<rev> would not.
|
||||
|
||||
The B<1> function uses a copy of the supplied structure pointer
|
||||
(or in some cases increases its link count) in the parent and
|
||||
so both (B<x> and B<obj> above) should be freed up.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
See the individual manual pages for details.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl(1)>, L<ssl(7)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,53 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ct - Certificate Transparency
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ct.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This library implements Certificate Transparency (CT) verification for TLS
|
||||
clients, as defined in RFC 6962. This verification can provide some confidence
|
||||
that a certificate has been publicly logged in a set of CT logs.
|
||||
|
||||
By default, these checks are disabled. They can be enabled using
|
||||
SSL_CTX_ct_enable() or SSL_ct_enable().
|
||||
|
||||
This library can also be used to parse and examine CT data structures, such as
|
||||
Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are
|
||||
functions for:
|
||||
- decoding and encoding SCTs in DER and TLS wire format.
|
||||
- printing SCTs.
|
||||
- verifying the authenticity of SCTs.
|
||||
- loading a CT log list from a CONF file.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<d2i_SCT_LIST(3)>,
|
||||
L<CTLOG_STORE_new(3)>,
|
||||
L<CTLOG_STORE_get0_log_by_id(3)>,
|
||||
L<SCT_new(3)>,
|
||||
L<SCT_print(3)>,
|
||||
L<SCT_validate(3)>,
|
||||
L<SCT_validate(3)>,
|
||||
L<CT_POLICY_EVAL_CTX_new(3)>,
|
||||
L<SSL_CTX_set_ct_validation_callback(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
This library was added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,258 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
des_modes - the variants of DES and other crypto algorithms of OpenSSL
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Several crypto algorithms for OpenSSL can be used in a number of modes. Those
|
||||
are used for using block ciphers in a way similar to stream ciphers, among
|
||||
other things.
|
||||
|
||||
=head1 OVERVIEW
|
||||
|
||||
=head2 Electronic Codebook Mode (ECB)
|
||||
|
||||
Normally, this is found as the function I<algorithm>_ecb_encrypt().
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
64 bits are enciphered at a time.
|
||||
|
||||
=item *
|
||||
|
||||
The order of the blocks can be rearranged without detection.
|
||||
|
||||
=item *
|
||||
|
||||
The same plaintext block always produces the same ciphertext block
|
||||
(for the same key) making it vulnerable to a 'dictionary attack'.
|
||||
|
||||
=item *
|
||||
|
||||
An error will only affect one ciphertext block.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Cipher Block Chaining Mode (CBC)
|
||||
|
||||
Normally, this is found as the function I<algorithm>_cbc_encrypt().
|
||||
Be aware that des_cbc_encrypt() is not really DES CBC (it does
|
||||
not update the IV); use des_ncbc_encrypt() instead.
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
a multiple of 64 bits are enciphered at a time.
|
||||
|
||||
=item *
|
||||
|
||||
The CBC mode produces the same ciphertext whenever the same
|
||||
plaintext is encrypted using the same key and starting variable.
|
||||
|
||||
=item *
|
||||
|
||||
The chaining operation makes the ciphertext blocks dependent on the
|
||||
current and all preceding plaintext blocks and therefore blocks can not
|
||||
be rearranged.
|
||||
|
||||
=item *
|
||||
|
||||
The use of different starting variables prevents the same plaintext
|
||||
enciphering to the same ciphertext.
|
||||
|
||||
=item *
|
||||
|
||||
An error will affect the current and the following ciphertext blocks.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Cipher Feedback Mode (CFB)
|
||||
|
||||
Normally, this is found as the function I<algorithm>_cfb_encrypt().
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
a number of bits (j) <= 64 are enciphered at a time.
|
||||
|
||||
=item *
|
||||
|
||||
The CFB mode produces the same ciphertext whenever the same
|
||||
plaintext is encrypted using the same key and starting variable.
|
||||
|
||||
=item *
|
||||
|
||||
The chaining operation makes the ciphertext variables dependent on the
|
||||
current and all preceding variables and therefore j-bit variables are
|
||||
chained together and can not be rearranged.
|
||||
|
||||
=item *
|
||||
|
||||
The use of different starting variables prevents the same plaintext
|
||||
enciphering to the same ciphertext.
|
||||
|
||||
=item *
|
||||
|
||||
The strength of the CFB mode depends on the size of k (maximal if
|
||||
j == k). In my implementation this is always the case.
|
||||
|
||||
=item *
|
||||
|
||||
Selection of a small value for j will require more cycles through
|
||||
the encipherment algorithm per unit of plaintext and thus cause
|
||||
greater processing overheads.
|
||||
|
||||
=item *
|
||||
|
||||
Only multiples of j bits can be enciphered.
|
||||
|
||||
=item *
|
||||
|
||||
An error will affect the current and the following ciphertext variables.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Output Feedback Mode (OFB)
|
||||
|
||||
Normally, this is found as the function I<algorithm>_ofb_encrypt().
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
a number of bits (j) <= 64 are enciphered at a time.
|
||||
|
||||
=item *
|
||||
|
||||
The OFB mode produces the same ciphertext whenever the same
|
||||
plaintext enciphered using the same key and starting variable. More
|
||||
over, in the OFB mode the same key stream is produced when the same
|
||||
key and start variable are used. Consequently, for security reasons
|
||||
a specific start variable should be used only once for a given key.
|
||||
|
||||
=item *
|
||||
|
||||
The absence of chaining makes the OFB more vulnerable to specific attacks.
|
||||
|
||||
=item *
|
||||
|
||||
The use of different start variables values prevents the same
|
||||
plaintext enciphering to the same ciphertext, by producing different
|
||||
key streams.
|
||||
|
||||
=item *
|
||||
|
||||
Selection of a small value for j will require more cycles through
|
||||
the encipherment algorithm per unit of plaintext and thus cause
|
||||
greater processing overheads.
|
||||
|
||||
=item *
|
||||
|
||||
Only multiples of j bits can be enciphered.
|
||||
|
||||
=item *
|
||||
|
||||
OFB mode of operation does not extend ciphertext errors in the
|
||||
resultant plaintext output. Every bit error in the ciphertext causes
|
||||
only one bit to be in error in the deciphered plaintext.
|
||||
|
||||
=item *
|
||||
|
||||
OFB mode is not self-synchronizing. If the two operation of
|
||||
encipherment and decipherment get out of synchronism, the system needs
|
||||
to be re-initialized.
|
||||
|
||||
=item *
|
||||
|
||||
Each re-initialization should use a value of the start variable
|
||||
different from the start variable values used before with the same
|
||||
key. The reason for this is that an identical bit stream would be
|
||||
produced each time from the same parameters. This would be
|
||||
susceptible to a 'known plaintext' attack.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Triple ECB Mode
|
||||
|
||||
Normally, this is found as the function I<algorithm>_ecb3_encrypt().
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
Encrypt with key1, decrypt with key2 and encrypt with key3 again.
|
||||
|
||||
=item *
|
||||
|
||||
As for ECB encryption but increases the key length to 168 bits.
|
||||
There are theoretic attacks that can be used that make the effective
|
||||
key length 112 bits, but this attack also requires 2^56 blocks of
|
||||
memory, not very likely, even for the NSA.
|
||||
|
||||
=item *
|
||||
|
||||
If both keys are the same it is equivalent to encrypting once with
|
||||
just one key.
|
||||
|
||||
=item *
|
||||
|
||||
If the first and last key are the same, the key length is 112 bits.
|
||||
There are attacks that could reduce the effective key strength
|
||||
to only slightly more than 56 bits, but these require a lot of memory.
|
||||
|
||||
=item *
|
||||
|
||||
If all 3 keys are the same, this is effectively the same as normal
|
||||
ecb mode.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Triple CBC Mode
|
||||
|
||||
Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
Encrypt with key1, decrypt with key2 and then encrypt with key3.
|
||||
|
||||
=item *
|
||||
|
||||
As for CBC encryption but increases the key length to 168 bits with
|
||||
the same restrictions as for triple ecb mode.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
This text was been written in large parts by Eric Young in his original
|
||||
documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed
|
||||
it to:
|
||||
|
||||
AS 2805.5.2
|
||||
Australian Standard
|
||||
Electronic funds transfer - Requirements for interfaces,
|
||||
Part 5.2: Modes of operation for an n-bit block cipher algorithm
|
||||
Appendix A
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BF_encrypt(3)>, L<DES_crypt(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,114 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
evp - high-level cryptographic functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/evp.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The EVP library provides a high-level interface to cryptographic
|
||||
functions.
|
||||
|
||||
The L<B<EVP_Seal>I<XXX>|EVP_SealInit(3)> and L<B<EVP_Open>I<XXX>|EVP_OpenInit(3)>
|
||||
functions provide public key encryption and decryption to implement digital "envelopes".
|
||||
|
||||
The L<B<EVP_DigestSign>I<XXX>|EVP_DigestSignInit(3)> and
|
||||
L<B<EVP_DigestVerify>I<XXX>|EVP_DigestVerifyInit(3)> functions implement
|
||||
digital signatures and Message Authentication Codes (MACs). Also see the older
|
||||
L<B<EVP_Sign>I<XXX>|EVP_SignInit(3)> and L<B<EVP_Verify>I<XXX>|EVP_VerifyInit(3)>
|
||||
functions.
|
||||
|
||||
Symmetric encryption is available with the L<B<EVP_Encrypt>I<XXX>|EVP_EncryptInit(3)>
|
||||
functions. The L<B<EVP_Digest>I<XXX>|EVP_DigestInit(3)> functions provide message digests.
|
||||
|
||||
The B<EVP_PKEY>I<XXX> functions provide a high level interface to
|
||||
asymmetric algorithms. To create a new EVP_PKEY see
|
||||
L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
|
||||
with a private key of a particular algorithm by using the functions
|
||||
described on the L<EVP_PKEY_set1_RSA(3)> page, or
|
||||
new keys can be generated using L<EVP_PKEY_keygen(3)>.
|
||||
EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
|
||||
L<EVP_PKEY_print_private(3)>.
|
||||
|
||||
The EVP_PKEY functions support the full range of asymmetric algorithm operations:
|
||||
|
||||
=over 4
|
||||
|
||||
=item For key agreement see L<EVP_PKEY_derive(3)>
|
||||
|
||||
=item For signing and verifying see L<EVP_PKEY_sign(3)>,
|
||||
L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>.
|
||||
However, note that
|
||||
these functions do not perform a digest of the data to be signed. Therefore
|
||||
normally you would use the L<EVP_DigestSignInit(3)>
|
||||
functions for this purpose.
|
||||
|
||||
=item For encryption and decryption see L<EVP_PKEY_encrypt(3)>
|
||||
and L<EVP_PKEY_decrypt(3)> respectively. However, note that
|
||||
these functions perform encryption and decryption only. As public key
|
||||
encryption is an expensive operation, normally you would wrap
|
||||
an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and
|
||||
L<EVP_OpenInit(3)> functions.
|
||||
|
||||
=back
|
||||
|
||||
The L<EVP_BytesToKey(3)> function provides some limited support for password
|
||||
based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
|
||||
implementation. However, new applications should not typically use this (preferring, for example,
|
||||
PBKDF2 from PCKS#5).
|
||||
|
||||
The L<B<EVP_Encode>I<XXX>|EVP_EncodeInit(3)> and
|
||||
L<B<EVP_Decode>I<XXX>|EVP_EncodeInit(3)> functions implement base 64 encoding
|
||||
and decoding.
|
||||
|
||||
All the symmetric algorithms (ciphers), digests and asymmetric algorithms
|
||||
(public key algorithms) can be replaced by ENGINE modules providing alternative
|
||||
implementations. If ENGINE implementations of ciphers or digests are registered
|
||||
as defaults, then the various EVP functions will automatically use those
|
||||
implementations automatically in preference to built in software
|
||||
implementations. For more information, consult the engine(3) man page.
|
||||
|
||||
Although low level algorithm specific functions exist for many algorithms
|
||||
their use is discouraged. They cannot be used with an ENGINE and ENGINE
|
||||
versions of new algorithms cannot be accessed using the low level functions.
|
||||
Also makes code harder to adapt to new algorithms and some options are not
|
||||
cleanly supported at the low level and some operations are more efficient
|
||||
using the high level interface.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_DigestInit(3)>,
|
||||
L<EVP_EncryptInit(3)>,
|
||||
L<EVP_OpenInit(3)>,
|
||||
L<EVP_SealInit(3)>,
|
||||
L<EVP_DigestSignInit(3)>,
|
||||
L<EVP_SignInit(3)>,
|
||||
L<EVP_VerifyInit(3)>,
|
||||
L<EVP_EncodeInit(3)>,
|
||||
L<EVP_PKEY_new(3)>,
|
||||
L<EVP_PKEY_set1_RSA(3)>,
|
||||
L<EVP_PKEY_keygen(3)>,
|
||||
L<EVP_PKEY_print_private(3)>,
|
||||
L<EVP_PKEY_decrypt(3)>,
|
||||
L<EVP_PKEY_encrypt(3)>,
|
||||
L<EVP_PKEY_sign(3)>,
|
||||
L<EVP_PKEY_verify(3)>,
|
||||
L<EVP_PKEY_verify_recover(3)>,
|
||||
L<EVP_PKEY_derive(3)>,
|
||||
L<EVP_BytesToKey(3)>,
|
||||
L<ENGINE_by_id(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,102 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ossl_store - Store retrieval functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
|
||||
#include <openssl/store.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
=head2 General
|
||||
|
||||
A STORE is a layer of functionality to retrieve a number of supported
|
||||
objects from a repository of any kind, addressable as a file name or
|
||||
as a URI.
|
||||
|
||||
The functionality supports the pattern "open a channel to the
|
||||
repository", "loop and retrieve one object at a time", and "finish up
|
||||
by closing the channel".
|
||||
|
||||
The retrieved objects are returned as a wrapper type B<OSSL_STORE_INFO>,
|
||||
from which an OpenSSL type can be retrieved.
|
||||
|
||||
=head2 URI schemes and loaders
|
||||
|
||||
Support for a URI scheme is called a STORE "loader", and can be added
|
||||
dynamically from the calling application or from a loadable engine.
|
||||
|
||||
=head2 The 'file' scheme
|
||||
|
||||
Support for the 'file' scheme is already built into C<libcrypto>.
|
||||
Since files come in all kinds of formats and content types, the 'file'
|
||||
scheme has its own layer of functionality called "file handlers",
|
||||
which are used to try to decode diverse types of file contents.
|
||||
|
||||
In case a file is formatted as PEM, each called file handler receives
|
||||
the PEM name (everything following any 'C<-----BEGIN >') as well as
|
||||
possible PEM headers, together with the decoded PEM body. Since PEM
|
||||
formatted files can contain more than one object, the file handlers
|
||||
are called upon for each such object.
|
||||
|
||||
If the file isn't determined to be formatted as PEM, the content is
|
||||
loaded in raw form in its entirety and passed to the available file
|
||||
handlers as is, with no PEM name or headers.
|
||||
|
||||
Each file handler is expected to handle PEM and non-PEM content as
|
||||
appropriate. Some may refuse non-PEM content for the sake of
|
||||
determinism (for example, there are keys out in the wild that are
|
||||
represented as an ASN.1 OCTET STRING. In raw form, it's not easily
|
||||
possible to distinguish those from any other data coming as an ASN.1
|
||||
OCTET STRING, so such keys would naturally be accepted as PEM files
|
||||
only).
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
=head2 A generic call
|
||||
|
||||
OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
|
||||
|
||||
/*
|
||||
* OSSL_STORE_eof() simulates file semantics for any repository to signal
|
||||
* that no more data can be expected
|
||||
*/
|
||||
while (!OSSL_STORE_eof(ctx)) {
|
||||
OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
|
||||
|
||||
/*
|
||||
* Do whatever is necessary with the OSSL_STORE_INFO,
|
||||
* here just one example
|
||||
*/
|
||||
switch (OSSL_STORE_INFO_get_type(info)) {
|
||||
case OSSL_STORE_INFO_X509:
|
||||
/* Print the X.509 certificate text */
|
||||
X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
|
||||
/* Print the X.509 certificate PEM output */
|
||||
PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
OSSL_STORE_close(ctx);
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
|
||||
L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>,
|
||||
L<OSSL_STORE_SEARCH(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,158 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
scrypt - EVP_PKEY scrypt KDF support
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/kdf.h>
|
||||
|
||||
int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,
|
||||
int passlen);
|
||||
|
||||
int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
|
||||
int saltlen);
|
||||
|
||||
int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);
|
||||
|
||||
int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);
|
||||
|
||||
int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);
|
||||
|
||||
int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, uint64_t maxmem);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
|
||||
derivation function, as described in RFC 7914. It is memory-hard in the sense
|
||||
that it deliberately requires a significant amount of RAM for efficient
|
||||
computation. The intention of this is to render brute forcing of passwords on
|
||||
systems that lack large amounts of main memory (such as GPUs or ASICs)
|
||||
computationally infeasible.
|
||||
|
||||
scrypt provides three work factors that can be customized: N, r and p. N, which
|
||||
has to be a positive power of two, is the general work factor and scales CPU
|
||||
time in an approximately linear fashion. r is the block size of the internally
|
||||
used hash function and p is the parallelization factor. Both r and p need to be
|
||||
greater than zero. The amount of RAM that scrypt requires for its computation
|
||||
is roughly (128 * N * r * p) bytes.
|
||||
|
||||
In the original paper of Colin Percival ("Stronger Key Derivation via
|
||||
Sequential Memory-Hard Functions", 2009), the suggested values that give a
|
||||
computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
|
||||
2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
|
||||
this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
|
||||
GHz), this computation takes about 3 seconds. When N, r or p are not specified,
|
||||
they default to 1048576, 8, and 1, respectively. The default amount of RAM that
|
||||
may be used by scrypt defaults to 1025 MiB.
|
||||
|
||||
EVP_PKEY_CTX_set1_pbe_pass() sets the B<passlen> bytes long password.
|
||||
|
||||
EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt value.
|
||||
|
||||
EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
|
||||
EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
|
||||
|
||||
EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may
|
||||
maximally use, given in bytes. If RAM is exceeded because the load factors are
|
||||
chosen too high, the key derivation will fail.
|
||||
|
||||
=head1 STRING CTRLS
|
||||
|
||||
scrypt also supports string based control operations via
|
||||
L<EVP_PKEY_CTX_ctrl_str(3)>.
|
||||
The B<password> can be directly specified using the B<type> parameter "pass" or
|
||||
given in hex encoding using the "hexpass" parameter. Similarly, the B<salt> can
|
||||
either be specified using the B<type> parameter "salt" or in hex encoding by
|
||||
using the "hexsalt" parameter. The work factors B<N>, B<r> and B<p> as well as
|
||||
B<maxmem_bytes> can be set by using the parameters "N", "r", "p" and
|
||||
"maxmem_bytes", respectively.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
All these functions are implemented as macros.
|
||||
|
||||
A context for scrypt can be obtained by calling:
|
||||
|
||||
EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_SCRYPT, NULL);
|
||||
|
||||
The output length of an scrypt key derivation is specified via the length
|
||||
parameter to the L<EVP_PKEY_derive(3)> function.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All these functions return 1 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 EXAMPLE
|
||||
|
||||
This example derives a 64-byte long test vector using scrypt using the password
|
||||
"password", salt "NaCl" and N = 1024, r = 8, p = 16.
|
||||
|
||||
EVP_PKEY_CTX *pctx;
|
||||
unsigned char out[64];
|
||||
|
||||
size_t outlen = sizeof(out);
|
||||
pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
|
||||
|
||||
if (EVP_PKEY_derive_init(pctx) <= 0) {
|
||||
error("EVP_PKEY_derive_init");
|
||||
}
|
||||
if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
|
||||
error("EVP_PKEY_CTX_set1_pbe_pass");
|
||||
}
|
||||
if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
|
||||
error("EVP_PKEY_CTX_set1_scrypt_salt");
|
||||
}
|
||||
if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
|
||||
error("EVP_PKEY_CTX_set_scrypt_N");
|
||||
}
|
||||
if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
|
||||
error("EVP_PKEY_CTX_set_scrypt_r");
|
||||
}
|
||||
if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
|
||||
error("EVP_PKEY_CTX_set_scrypt_p");
|
||||
}
|
||||
if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
|
||||
error("EVP_PKEY_derive");
|
||||
}
|
||||
|
||||
{
|
||||
const unsigned char expected[sizeof(out)] = {
|
||||
0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
|
||||
0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
|
||||
0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
|
||||
0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
|
||||
0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
|
||||
0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
|
||||
0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
|
||||
0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
|
||||
};
|
||||
|
||||
assert(!memcmp(out, expected, sizeof(out)));
|
||||
}
|
||||
|
||||
EVP_PKEY_CTX_free(pctx);
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
RFC 7914
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_CTX_new(3)>,
|
||||
L<EVP_PKEY_CTX_ctrl_str(3)>,
|
||||
L<EVP_PKEY_derive(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,843 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ssl - OpenSSL SSL/TLS library
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
See the individual manual pages for details.
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
|
||||
Transport Layer Security (TLS v1) protocols. It provides a rich API which is
|
||||
documented here.
|
||||
|
||||
An B<SSL_CTX> object is created as a framework to establish
|
||||
TLS/SSL enabled connections (see L<SSL_CTX_new(3)>).
|
||||
Various options regarding certificates, algorithms etc. can be set
|
||||
in this object.
|
||||
|
||||
When a network connection has been created, it can be assigned to an
|
||||
B<SSL> object. After the B<SSL> object has been created using
|
||||
L<SSL_new(3)>, L<SSL_set_fd(3)> or
|
||||
L<SSL_set_bio(3)> can be used to associate the network
|
||||
connection with the object.
|
||||
|
||||
When the TLS/SSL handshake is performed using
|
||||
L<SSL_accept(3)> or L<SSL_connect(3)>
|
||||
respectively.
|
||||
L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are
|
||||
used to read and write data on the TLS/SSL connection.
|
||||
L<SSL_shutdown(3)> can be used to shut down the
|
||||
TLS/SSL connection.
|
||||
|
||||
=head1 DATA STRUCTURES
|
||||
|
||||
Currently the OpenSSL B<ssl> library functions deals with the following data
|
||||
structures:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<SSL_METHOD> (SSL Method)
|
||||
|
||||
This is a dispatch structure describing the internal B<ssl> library
|
||||
methods/functions which implement the various protocol versions (SSLv3
|
||||
TLSv1, ...). It's needed to create an B<SSL_CTX>.
|
||||
|
||||
=item B<SSL_CIPHER> (SSL Cipher)
|
||||
|
||||
This structure holds the algorithm information for a particular cipher which
|
||||
are a core part of the SSL/TLS protocol. The available ciphers are configured
|
||||
on a B<SSL_CTX> basis and the actual ones used are then part of the
|
||||
B<SSL_SESSION>.
|
||||
|
||||
=item B<SSL_CTX> (SSL Context)
|
||||
|
||||
This is the global context structure which is created by a server or client
|
||||
once per program life-time and which holds mainly default values for the
|
||||
B<SSL> structures which are later created for the connections.
|
||||
|
||||
=item B<SSL_SESSION> (SSL Session)
|
||||
|
||||
This is a structure containing the current TLS/SSL session details for a
|
||||
connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
|
||||
|
||||
=item B<SSL> (SSL Connection)
|
||||
|
||||
This is the main SSL/TLS structure which is created by a server or client per
|
||||
established connection. This actually is the core structure in the SSL API.
|
||||
At run-time the application usually deals with this structure which has
|
||||
links to mostly all other structures.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 HEADER FILES
|
||||
|
||||
Currently the OpenSSL B<ssl> library provides the following C header files
|
||||
containing the prototypes for the data structures and functions:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<ssl.h>
|
||||
|
||||
This is the common header file for the SSL/TLS API. Include it into your
|
||||
program to make the API of the B<ssl> library available. It internally
|
||||
includes both more private SSL headers and headers from the B<crypto> library.
|
||||
Whenever you need hard-core details on the internals of the SSL API, look
|
||||
inside this header file.
|
||||
|
||||
OPENSSL_VERSION_AT_LEAST(major,minor) can be
|
||||
used in C<#if> statements in order to determine which version of the library is
|
||||
being used. This can be used to either enable optional features at compile
|
||||
time, or work around issues with a previous version.
|
||||
See L<OPENSSL_VERSION_NUMBER(3)>.
|
||||
|
||||
=item B<ssl2.h>
|
||||
|
||||
Unused. Present for backwards compatibility only.
|
||||
|
||||
=item B<ssl3.h>
|
||||
|
||||
This is the sub header file dealing with the SSLv3 protocol only.
|
||||
I<Usually you don't have to include it explicitly because
|
||||
it's already included by ssl.h>.
|
||||
|
||||
=item B<tls1.h>
|
||||
|
||||
This is the sub header file dealing with the TLSv1 protocol only.
|
||||
I<Usually you don't have to include it explicitly because
|
||||
it's already included by ssl.h>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 API FUNCTIONS
|
||||
|
||||
Currently the OpenSSL B<ssl> library exports 214 API functions.
|
||||
They are documented in the following:
|
||||
|
||||
=head2 Dealing with Protocol Methods
|
||||
|
||||
Here we document the various API functions which deal with the SSL/TLS
|
||||
protocol methods defined in B<SSL_METHOD> structures.
|
||||
|
||||
=over 4
|
||||
|
||||
=item const SSL_METHOD *B<TLS_method>(void);
|
||||
|
||||
Constructor for the I<version-flexible> SSL_METHOD structure for clients,
|
||||
servers or both.
|
||||
See L<SSL_CTX_new(3)> for details.
|
||||
|
||||
=item const SSL_METHOD *B<TLS_client_method>(void);
|
||||
|
||||
Constructor for the I<version-flexible> SSL_METHOD structure for clients.
|
||||
|
||||
=item const SSL_METHOD *B<TLS_server_method>(void);
|
||||
|
||||
Constructor for the I<version-flexible> SSL_METHOD structure for servers.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_2_method>(void);
|
||||
|
||||
Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_2_client_method>(void);
|
||||
|
||||
Constructor for the TLSv1.2 SSL_METHOD structure for clients.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_2_server_method>(void);
|
||||
|
||||
Constructor for the TLSv1.2 SSL_METHOD structure for servers.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_1_method>(void);
|
||||
|
||||
Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_1_client_method>(void);
|
||||
|
||||
Constructor for the TLSv1.1 SSL_METHOD structure for clients.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_1_server_method>(void);
|
||||
|
||||
Constructor for the TLSv1.1 SSL_METHOD structure for servers.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_method>(void);
|
||||
|
||||
Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_client_method>(void);
|
||||
|
||||
Constructor for the TLSv1 SSL_METHOD structure for clients.
|
||||
|
||||
=item const SSL_METHOD *B<TLSv1_server_method>(void);
|
||||
|
||||
Constructor for the TLSv1 SSL_METHOD structure for servers.
|
||||
|
||||
=item const SSL_METHOD *B<SSLv3_method>(void);
|
||||
|
||||
Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both.
|
||||
|
||||
=item const SSL_METHOD *B<SSLv3_client_method>(void);
|
||||
|
||||
Constructor for the SSLv3 SSL_METHOD structure for clients.
|
||||
|
||||
=item const SSL_METHOD *B<SSLv3_server_method>(void);
|
||||
|
||||
Constructor for the SSLv3 SSL_METHOD structure for servers.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Dealing with Ciphers
|
||||
|
||||
Here we document the various API functions which deal with the SSL/TLS
|
||||
ciphers defined in B<SSL_CIPHER> structures.
|
||||
|
||||
=over 4
|
||||
|
||||
=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len);
|
||||
|
||||
Write a string to I<buf> (with a maximum size of I<len>) containing a human
|
||||
readable description of I<cipher>. Returns I<buf>.
|
||||
|
||||
=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits);
|
||||
|
||||
Determine the number of bits in I<cipher>. Because of export crippled ciphers
|
||||
there are two bits: The bits the algorithm supports in general (stored to
|
||||
I<alg_bits>) and the bits which are actually used (the return value).
|
||||
|
||||
=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher);
|
||||
|
||||
Return the internal name of I<cipher> as a string. These are the various
|
||||
strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx>
|
||||
definitions in the header files.
|
||||
|
||||
=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher);
|
||||
|
||||
Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the
|
||||
SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined
|
||||
in the specification the first time).
|
||||
|
||||
=back
|
||||
|
||||
=head2 Dealing with Protocol Contexts
|
||||
|
||||
Here we document the various API functions which deal with the SSL/TLS
|
||||
protocol context defined in the B<SSL_CTX> structure.
|
||||
|
||||
=over 4
|
||||
|
||||
=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x);
|
||||
|
||||
=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509);
|
||||
|
||||
=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c);
|
||||
|
||||
=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx);
|
||||
|
||||
=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg);
|
||||
|
||||
=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t);
|
||||
|
||||
=item void B<SSL_CTX_free>(SSL_CTX *a);
|
||||
|
||||
=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx);
|
||||
|
||||
=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx);
|
||||
|
||||
=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx);
|
||||
|
||||
=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx);
|
||||
|
||||
=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
|
||||
|
||||
=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx);
|
||||
|
||||
=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
|
||||
|
||||
=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
|
||||
|
||||
=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
|
||||
|
||||
=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
|
||||
|
||||
=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
|
||||
|
||||
=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
|
||||
|
||||
=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath);
|
||||
|
||||
=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth);
|
||||
|
||||
=item int SSL_CTX_up_ref(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
|
||||
|
||||
=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx);
|
||||
|
||||
=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);
|
||||
|
||||
=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);
|
||||
|
||||
=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);
|
||||
|
||||
=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx);
|
||||
|
||||
=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t);
|
||||
|
||||
=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
|
||||
|
||||
=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
|
||||
|
||||
=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
|
||||
|
||||
=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx);
|
||||
|
||||
=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
|
||||
|
||||
=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
|
||||
|
||||
=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
|
||||
|
||||
=item void B<SSL_CTX_set1_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
|
||||
|
||||
=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg)
|
||||
|
||||
=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str);
|
||||
|
||||
=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list);
|
||||
|
||||
=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
|
||||
|
||||
=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);
|
||||
|
||||
=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void))
|
||||
|
||||
=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m);
|
||||
|
||||
=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
|
||||
|
||||
Use the default paths to locate trusted CA certificates. There is one default
|
||||
directory path and one default file path. Both are set via this call.
|
||||
|
||||
=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx)
|
||||
|
||||
Use the default directory path to locate trusted CA certificates.
|
||||
|
||||
=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx)
|
||||
|
||||
Use the file path to locate trusted CA certificates.
|
||||
|
||||
=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
|
||||
|
||||
=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
|
||||
|
||||
=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
|
||||
|
||||
=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg);
|
||||
|
||||
=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op);
|
||||
|
||||
=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx);
|
||||
|
||||
=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op);
|
||||
|
||||
=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
|
||||
|
||||
=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m);
|
||||
|
||||
=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
|
||||
|
||||
=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth);
|
||||
|
||||
=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t);
|
||||
|
||||
=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh);
|
||||
|
||||
=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void));
|
||||
|
||||
=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void))
|
||||
|
||||
=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey);
|
||||
|
||||
=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len);
|
||||
|
||||
=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
|
||||
|
||||
=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa);
|
||||
|
||||
=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len);
|
||||
|
||||
=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
|
||||
|
||||
=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x);
|
||||
|
||||
=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d);
|
||||
|
||||
=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type);
|
||||
|
||||
=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx);
|
||||
|
||||
=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx);
|
||||
|
||||
=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
|
||||
|
||||
=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint);
|
||||
|
||||
=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
|
||||
|
||||
|
||||
=back
|
||||
|
||||
=head2 Dealing with Sessions
|
||||
|
||||
Here we document the various API functions which deal with the SSL/TLS
|
||||
sessions defined in the B<SSL_SESSION> structures.
|
||||
|
||||
=over 4
|
||||
|
||||
=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b);
|
||||
|
||||
=item void B<SSL_SESSION_free>(SSL_SESSION *ss);
|
||||
|
||||
=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s);
|
||||
|
||||
=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx);
|
||||
|
||||
=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
|
||||
|
||||
=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s);
|
||||
|
||||
=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s);
|
||||
|
||||
=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a);
|
||||
|
||||
=item SSL_SESSION *B<SSL_SESSION_new>(void);
|
||||
|
||||
=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x);
|
||||
|
||||
=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
|
||||
|
||||
=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
|
||||
|
||||
=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);
|
||||
|
||||
=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t);
|
||||
|
||||
=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t);
|
||||
|
||||
=back
|
||||
|
||||
=head2 Dealing with Connections
|
||||
|
||||
Here we document the various API functions which deal with the SSL/TLS
|
||||
connection defined in the B<SSL> structure.
|
||||
|
||||
=over 4
|
||||
|
||||
=item int B<SSL_accept>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir);
|
||||
|
||||
=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file);
|
||||
|
||||
=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x);
|
||||
|
||||
=item char *B<SSL_alert_desc_string>(int value);
|
||||
|
||||
=item char *B<SSL_alert_desc_string_long>(int value);
|
||||
|
||||
=item char *B<SSL_alert_type_string>(int value);
|
||||
|
||||
=item char *B<SSL_alert_type_string_long>(int value);
|
||||
|
||||
=item int B<SSL_check_private_key>(const SSL *ssl);
|
||||
|
||||
=item void B<SSL_clear>(SSL *ssl);
|
||||
|
||||
=item long B<SSL_clear_num_renegotiations>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_connect>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_copy_session_id>(SSL *t, const SSL *f);
|
||||
|
||||
Sets the session details for B<t> to be the same as in B<f>. Returns 1 on
|
||||
success or 0 on failure.
|
||||
|
||||
=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg);
|
||||
|
||||
=item int B<SSL_do_handshake>(SSL *ssl);
|
||||
|
||||
=item SSL *B<SSL_dup>(SSL *ssl);
|
||||
|
||||
SSL_dup() allows applications to configure an SSL handle for use
|
||||
in multiple SSL connections, and then duplicate it prior to initiating
|
||||
each connection with the duplicated handle.
|
||||
Use of SSL_dup() avoids the need to repeat the configuration of the
|
||||
handles for each connection.
|
||||
|
||||
For SSL_dup() to work, the connection MUST be in its initial state
|
||||
and MUST NOT have not yet have started the SSL handshake.
|
||||
For connections that are not in their initial state SSL_dup() just
|
||||
increments an internal reference count and returns the I<same>
|
||||
handle.
|
||||
It may be possible to use L<SSL_clear(3)> to recycle an SSL handle
|
||||
that is not in its initial state for re-use, but this is best
|
||||
avoided.
|
||||
Instead, save and restore the session, if desired, and construct a
|
||||
fresh handle for each connection.
|
||||
|
||||
=item STACK *B<SSL_dup_CA_list>(STACK *sk);
|
||||
|
||||
=item void B<SSL_free>(SSL *ssl);
|
||||
|
||||
=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl);
|
||||
|
||||
=item char *B<SSL_get_app_data>(SSL *ssl);
|
||||
|
||||
=item X509 *B<SSL_get_certificate>(const SSL *ssl);
|
||||
|
||||
=item const char *B<SSL_get_cipher>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_is_dtls>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits);
|
||||
|
||||
=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n);
|
||||
|
||||
=item char *B<SSL_get_cipher_name>(const SSL *ssl);
|
||||
|
||||
=item char *B<SSL_get_cipher_version>(const SSL *ssl);
|
||||
|
||||
=item STACK *B<SSL_get_ciphers>(const SSL *ssl);
|
||||
|
||||
=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl);
|
||||
|
||||
=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl);
|
||||
|
||||
=item long B<SSL_get_default_timeout>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_get_error>(const SSL *ssl, int i);
|
||||
|
||||
=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx);
|
||||
|
||||
=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void);
|
||||
|
||||
=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
|
||||
|
||||
=item int B<SSL_get_fd>(const SSL *ssl);
|
||||
|
||||
=item void (*B<SSL_get_info_callback>(const SSL *ssl);)()
|
||||
|
||||
=item int B<SSL_get_key_update_type>(SSL *s);
|
||||
|
||||
=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl);
|
||||
|
||||
=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl);
|
||||
|
||||
=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s);
|
||||
|
||||
=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_get_quiet_shutdown>(const SSL *ssl);
|
||||
|
||||
=item BIO *B<SSL_get_rbio>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_get_read_ahead>(const SSL *ssl);
|
||||
|
||||
=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
|
||||
|
||||
=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len);
|
||||
|
||||
=item int B<SSL_get_shutdown>(const SSL *ssl);
|
||||
|
||||
=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_get_state>(const SSL *ssl);
|
||||
|
||||
=item long B<SSL_get_time>(const SSL *ssl);
|
||||
|
||||
=item long B<SSL_get_timeout>(const SSL *ssl);
|
||||
|
||||
=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *)
|
||||
|
||||
=item int B<SSL_get_verify_mode>(const SSL *ssl);
|
||||
|
||||
=item long B<SSL_get_verify_result>(const SSL *ssl);
|
||||
|
||||
=item char *B<SSL_get_version>(const SSL *ssl);
|
||||
|
||||
=item BIO *B<SSL_get_wbio>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_in_accept_init>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_in_before>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_in_connect_init>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_in_init>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_is_init_finished>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_key_update>(SSL *s, int updatetype);
|
||||
|
||||
=item STACK *B<SSL_load_client_CA_file>(const char *file);
|
||||
|
||||
=item SSL *B<SSL_new>(SSL_CTX *ctx);
|
||||
|
||||
=item int SSL_up_ref(SSL *s);
|
||||
|
||||
=item long B<SSL_num_renegotiations>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_peek>(SSL *ssl, void *buf, int num);
|
||||
|
||||
=item int B<SSL_pending>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_read>(SSL *ssl, void *buf, int num);
|
||||
|
||||
=item int B<SSL_renegotiate>(SSL *ssl);
|
||||
|
||||
=item char *B<SSL_rstate_string>(SSL *ssl);
|
||||
|
||||
=item char *B<SSL_rstate_string_long>(SSL *ssl);
|
||||
|
||||
=item long B<SSL_session_reused>(SSL *ssl);
|
||||
|
||||
=item void B<SSL_set_accept_state>(SSL *ssl);
|
||||
|
||||
=item void B<SSL_set_app_data>(SSL *ssl, char *arg);
|
||||
|
||||
=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio);
|
||||
|
||||
=item int B<SSL_set_cipher_list>(SSL *ssl, char *str);
|
||||
|
||||
=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list);
|
||||
|
||||
=item void B<SSL_set_connect_state>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg);
|
||||
|
||||
=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg);
|
||||
|
||||
=item int B<SSL_set_fd>(SSL *ssl, int fd);
|
||||
|
||||
=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void))
|
||||
|
||||
=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
|
||||
|
||||
=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg);
|
||||
|
||||
=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op);
|
||||
|
||||
=item unsigned long B<SSL_get_options>(SSL *ssl);
|
||||
|
||||
=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op);
|
||||
|
||||
=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode);
|
||||
|
||||
=item void B<SSL_set_read_ahead>(SSL *ssl, int yes);
|
||||
|
||||
=item int B<SSL_set_rfd>(SSL *ssl, int fd);
|
||||
|
||||
=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session);
|
||||
|
||||
=item void B<SSL_set_shutdown>(SSL *ssl, int mode);
|
||||
|
||||
=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth);
|
||||
|
||||
=item void B<SSL_set_time>(SSL *ssl, long t);
|
||||
|
||||
=item void B<SSL_set_timeout>(SSL *ssl, long t);
|
||||
|
||||
=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void))
|
||||
|
||||
=item void B<SSL_set_verify_result>(SSL *ssl, long arg);
|
||||
|
||||
=item int B<SSL_set_wfd>(SSL *ssl, int fd);
|
||||
|
||||
=item int B<SSL_shutdown>(SSL *ssl);
|
||||
|
||||
=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl);
|
||||
|
||||
Returns the current handshake state.
|
||||
|
||||
=item char *B<SSL_state_string>(const SSL *ssl);
|
||||
|
||||
=item char *B<SSL_state_string_long>(const SSL *ssl);
|
||||
|
||||
=item long B<SSL_total_renegotiations>(SSL *ssl);
|
||||
|
||||
=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey);
|
||||
|
||||
=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len);
|
||||
|
||||
=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type);
|
||||
|
||||
=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa);
|
||||
|
||||
=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len);
|
||||
|
||||
=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type);
|
||||
|
||||
=item int B<SSL_use_certificate>(SSL *ssl, X509 *x);
|
||||
|
||||
=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d);
|
||||
|
||||
=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type);
|
||||
|
||||
=item int B<SSL_version>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_want>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_want_nothing>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_want_read>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_want_write>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_want_x509_lookup>(const SSL *ssl);
|
||||
|
||||
=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
|
||||
|
||||
=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
|
||||
|
||||
=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint);
|
||||
|
||||
=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
|
||||
|
||||
=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl);
|
||||
|
||||
=item const char *B<SSL_get_psk_identity>(SSL *ssl);
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
See the individual manual pages for details.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl(1)>, L<crypto(7)>,
|
||||
L<CRYPTO_get_ex_new_index(3)>,
|
||||
L<SSL_accept(3)>, L<SSL_clear(3)>,
|
||||
L<SSL_connect(3)>,
|
||||
L<SSL_CIPHER_get_name(3)>,
|
||||
L<SSL_COMP_add_compression_method(3)>,
|
||||
L<SSL_CTX_add_extra_chain_cert(3)>,
|
||||
L<SSL_CTX_add_session(3)>,
|
||||
L<SSL_CTX_ctrl(3)>,
|
||||
L<SSL_CTX_flush_sessions(3)>,
|
||||
L<SSL_CTX_get_verify_mode(3)>,
|
||||
L<SSL_CTX_load_verify_locations(3)>
|
||||
L<SSL_CTX_new(3)>,
|
||||
L<SSL_CTX_sess_number(3)>,
|
||||
L<SSL_CTX_sess_set_cache_size(3)>,
|
||||
L<SSL_CTX_sess_set_get_cb(3)>,
|
||||
L<SSL_CTX_sessions(3)>,
|
||||
L<SSL_CTX_set_cert_store(3)>,
|
||||
L<SSL_CTX_set_cert_verify_callback(3)>,
|
||||
L<SSL_CTX_set_cipher_list(3)>,
|
||||
L<SSL_CTX_set_client_CA_list(3)>,
|
||||
L<SSL_CTX_set_client_cert_cb(3)>,
|
||||
L<SSL_CTX_set_default_passwd_cb(3)>,
|
||||
L<SSL_CTX_set_generate_session_id(3)>,
|
||||
L<SSL_CTX_set_info_callback(3)>,
|
||||
L<SSL_CTX_set_max_cert_list(3)>,
|
||||
L<SSL_CTX_set_mode(3)>,
|
||||
L<SSL_CTX_set_msg_callback(3)>,
|
||||
L<SSL_CTX_set_options(3)>,
|
||||
L<SSL_CTX_set_quiet_shutdown(3)>,
|
||||
L<SSL_CTX_set_read_ahead(3)>,
|
||||
L<SSL_CTX_set_security_level(3)>,
|
||||
L<SSL_CTX_set_session_cache_mode(3)>,
|
||||
L<SSL_CTX_set_session_id_context(3)>,
|
||||
L<SSL_CTX_set_ssl_version(3)>,
|
||||
L<SSL_CTX_set_timeout(3)>,
|
||||
L<SSL_CTX_set_tmp_dh_callback(3)>,
|
||||
L<SSL_CTX_set_verify(3)>,
|
||||
L<SSL_CTX_use_certificate(3)>,
|
||||
L<SSL_alert_type_string(3)>,
|
||||
L<SSL_do_handshake(3)>,
|
||||
L<SSL_enable_ct(3)>,
|
||||
L<SSL_get_SSL_CTX(3)>,
|
||||
L<SSL_get_ciphers(3)>,
|
||||
L<SSL_get_client_CA_list(3)>,
|
||||
L<SSL_get_default_timeout(3)>,
|
||||
L<SSL_get_error(3)>,
|
||||
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
|
||||
L<SSL_get_fd(3)>,
|
||||
L<SSL_get_peer_cert_chain(3)>,
|
||||
L<SSL_get_rbio(3)>,
|
||||
L<SSL_get_session(3)>,
|
||||
L<SSL_get_verify_result(3)>,
|
||||
L<SSL_get_version(3)>,
|
||||
L<SSL_load_client_CA_file(3)>,
|
||||
L<SSL_new(3)>,
|
||||
L<SSL_pending(3)>,
|
||||
L<SSL_read_ex(3)>,
|
||||
L<SSL_read(3)>,
|
||||
L<SSL_rstate_string(3)>,
|
||||
L<SSL_session_reused(3)>,
|
||||
L<SSL_set_bio(3)>,
|
||||
L<SSL_set_connect_state(3)>,
|
||||
L<SSL_set_fd(3)>,
|
||||
L<SSL_set_session(3)>,
|
||||
L<SSL_set_shutdown(3)>,
|
||||
L<SSL_shutdown(3)>,
|
||||
L<SSL_state_string(3)>,
|
||||
L<SSL_want(3)>,
|
||||
L<SSL_write_ex(3)>,
|
||||
L<SSL_write(3)>,
|
||||
L<SSL_SESSION_free(3)>,
|
||||
L<SSL_SESSION_get_time(3)>,
|
||||
L<d2i_SSL_SESSION(3)>,
|
||||
L<SSL_CTX_set_psk_client_callback(3)>,
|
||||
L<SSL_CTX_use_psk_identity_hint(3)>,
|
||||
L<SSL_get_psk_identity(3)>,
|
||||
L<DTLSv1_listen(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> where removed
|
||||
in OpenSSL 1.1.0.
|
||||
|
||||
The return type of B<SSL_copy_session_id> was changed from void to int in
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,73 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
x509 - X.509 certificate handling
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/x509.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
An X.509 certificate is a structured grouping of information about
|
||||
an individual, a device, or anything one can imagine. A X.509 CRL
|
||||
(certificate revocation list) is a tool to help determine if a
|
||||
certificate is still valid. The exact definition of those can be
|
||||
found in the X.509 document from ITU-T, or in RFC3280 from PKIX.
|
||||
In OpenSSL, the type X509 is used to express such a certificate, and
|
||||
the type X509_CRL is used to express a CRL.
|
||||
|
||||
A related structure is a certificate request, defined in PKCS#10 from
|
||||
RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type
|
||||
X509_REQ is used to express such a certificate request.
|
||||
|
||||
To handle some complex parts of a certificate, there are the types
|
||||
X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express
|
||||
a certificate attributes), X509_EXTENSION (to express a certificate
|
||||
extension) and a few more.
|
||||
|
||||
Finally, there's the supertype X509_INFO, which can contain a CRL, a
|
||||
certificate and a corresponding private key.
|
||||
|
||||
B<X509_>I<XXX>, B<d2i_X509_>I<XXX>, and B<i2d_X509_>I<XXX> functions
|
||||
handle X.509 certificates, with some exceptions, shown below.
|
||||
|
||||
B<X509_CRL_>I<XXX>, B<d2i_X509_CRL_>I<XXX>, and B<i2d_X509_CRL_>I<XXX>
|
||||
functions handle X.509 CRLs.
|
||||
|
||||
B<X509_REQ_>I<XXX>, B<d2i_X509_REQ_>I<XXX>, and B<i2d_X509_REQ_>I<XXX>
|
||||
functions handle PKCS#10 certificate requests.
|
||||
|
||||
B<X509_NAME_>I<XXX> functions handle certificate names.
|
||||
|
||||
B<X509_ATTRIBUTE_>I<XXX> functions handle certificate attributes.
|
||||
|
||||
B<X509_EXTENSION_>I<XXX> functions handle certificate extensions.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<X509_NAME_ENTRY_get_object(3)>,
|
||||
L<X509_NAME_add_entry_by_txt(3)>,
|
||||
L<X509_NAME_add_entry_by_NID(3)>,
|
||||
L<X509_NAME_print_ex(3)>,
|
||||
L<X509_NAME_new(3)>,
|
||||
L<d2i_X509(3)>,
|
||||
L<d2i_X509_ALGOR(3)>,
|
||||
L<d2i_X509_CRL(3)>,
|
||||
L<d2i_X509_NAME(3)>,
|
||||
L<d2i_X509_REQ(3)>,
|
||||
L<d2i_X509_SIG(3)>,
|
||||
L<X509v3(3)>,
|
||||
L<crypto(7)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
Reference in New Issue
Block a user