diff options
Diffstat (limited to 'deps/openssl/openssl/doc/man7')
| -rw-r--r-- | deps/openssl/openssl/doc/man7/Ed25519.pod | 87 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/RAND.pod | 81 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/RAND_DRBG.pod | 301 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/RSA-PSS.pod | 61 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/SM2.pod | 79 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/X25519.pod | 74 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/bio.pod | 87 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/crypto.pod | 60 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/ct.pod | 53 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/des_modes.pod | 258 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/evp.pod | 114 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/ossl_store-file.pod | 71 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/ossl_store.pod | 87 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/passphrase-encoding.pod | 180 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/scrypt.pod | 115 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/ssl.pod | 843 | ||||
| -rw-r--r-- | deps/openssl/openssl/doc/man7/x509.pod | 73 |
17 files changed, 2624 insertions, 0 deletions
diff --git a/deps/openssl/openssl/doc/man7/Ed25519.pod b/deps/openssl/openssl/doc/man7/Ed25519.pod new file mode 100644 index 0000000000..3f54217918 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/Ed25519.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +Ed25519, +Ed448 +- EVP_PKEY Ed25519 and Ed448 support + +=head1 DESCRIPTION + +The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key generation, +one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448> +(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, a digest must B<NOT> be +specified when signing or verifying. + +=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() and EVP_DigestVerify() functions. + +When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the +digest B<type> parameter B<MUST> be set to B<NULL>. + +Applications wishing to sign certificates (or other structures such as +CRLs or certificate requests) using Ed25519 or Ed448 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); + +For the B<Ed448> algorithm a context can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL); + +Ed25519 or Ed448 private keys can be set directly using +L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file +using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. + +Ed25519 or Ed448 public keys can be set directly using +L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo +structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function). + +Ed25519 and Ed448 can be tested within L<speed(1)> application since version 1.1.1. +Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is +specified, then both Ed25519 and Ed448 are benchmarked. + +=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-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 diff --git a/deps/openssl/openssl/doc/man7/RAND.pod b/deps/openssl/openssl/doc/man7/RAND.pod new file mode 100644 index 0000000000..971b3cdb16 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/RAND.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +RAND +- the OpenSSL random generator + +=head1 DESCRIPTION + +Random numbers are a vital part of cryptography, they are needed to provide +unpredictability for tasks like key generation, creating salts, and many more. +Software-based generators must be seeded with external randomness before they +can be used as a cryptographically-secure pseudo-random number generator +(CSPRNG). +The availability of common hardware with special instructions and +modern operating systems, which may use items such as interrupt jitter +and network packet timings, can be reasonable sources of seeding material. + +OpenSSL comes with a default implementation of the RAND API which is based on +the deterministic random bit generator (DRBG) model as described in +[NIST SP 800-90A Rev. 1]. The default random generator will initialize +automatically on first use and will be fully functional without having +to be initialized ('seeded') explicitly. +It seeds and reseeds itself automatically using trusted random sources +provided by the operating system. + +As a normal application developer, you do not have to worry about any details, +just use L<RAND_bytes(3)> to obtain random data. +Having said that, there is one important rule to obey: Always check the error +return value of L<RAND_bytes(3)> and do not take randomness for granted. + +For values that should remain secret, you can use L<RAND_priv_bytes(3)> +instead. +This method does not provide 'better' randomness, it uses the same type of CSPRNG. +The intention behind using a dedicated CSPRNG exclusively for private +values is that none of its output should be visible to an attacker (e.g., +used as salt value), in order to reveal as little information as +possible about its internal state, and that a compromise of the "public" +CSPRNG instance will not affect the secrecy of these private values. + +In the rare case where the default implementation does not satisfy your special +requirements, there are two options: + +=over 2 + +=item * + +Replace the default RAND method by your own RAND method using +L<RAND_set_rand_method(3)>. + +=item * + +Modify the default settings of the OpenSSL RAND method by modifying the security +parameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>. + +=back + +Changing the default random generator or its default parameters should be necessary +only in exceptional cases and is not recommended, unless you have a profound knowledge +of cryptographic principles and understand the implications of your changes. + +=head1 SEE ALSO + +L<RAND_add(3)>, +L<RAND_bytes(3)>, +L<RAND_priv_bytes(3)>, +L<RAND_get_rand_method(3)>, +L<RAND_set_rand_method(3)>, +L<RAND_OpenSSL(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 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 diff --git a/deps/openssl/openssl/doc/man7/RAND_DRBG.pod b/deps/openssl/openssl/doc/man7/RAND_DRBG.pod new file mode 100644 index 0000000000..ba457f0504 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/RAND_DRBG.pod @@ -0,0 +1,301 @@ +=pod + +=head1 NAME + +RAND_DRBG - the deterministic random bit generator + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + +=head1 DESCRIPTION + +The default OpenSSL RAND method is based on the RAND_DRBG class, +which implements a deterministic random bit generator (DRBG). +A DRBG is a certain type of cryptographically-secure pseudo-random +number generator (CSPRNG), which is described in +[NIST SP 800-90A Rev. 1]. + +While the RAND API is the 'frontend' which is intended to be used by +application developers for obtaining random bytes, the RAND_DRBG API +serves as the 'backend', connecting the former with the operating +systems's entropy sources and providing access to the DRBG's +configuration parameters. + +=head2 Disclaimer + +Unless you have very specific requirements for your random generator, +it is in general not necessary to utilize the RAND_DRBG API directly. +The usual way to obtain random bytes is to use L<RAND_bytes(3)> or +L<RAND_priv_bytes(3)>, see also L<RAND(7)>. + +=head2 Typical Use Cases + +Typical examples for such special use cases are the following: + +=over 2 + +=item * + +You want to use your own private DRBG instances. +Multiple DRBG instances which are accessed only by a single thread provide +additional security (because their internal states are independent) and +better scalability in multithreaded applications (because they don't need +to be locked). + +=item * + +You need to integrate a previously unsupported entropy source. + +=item * + +You need to change the default settings of the standard OpenSSL RAND +implementation to meet specific requirements. + +=back + + +=head1 CHAINING + +A DRBG instance can be used as the entropy source of another DRBG instance, +provided it has itself access to a valid entropy source. +The DRBG instance which acts as entropy source is called the I<parent> DRBG, +the other instance the I<child> DRBG. + +This is called chaining. A chained DRBG instance is created by passing +a pointer to the parent DRBG as argument to the RAND_DRBG_new() call. +It is possible to create chains of more than two DRBG in a row. + +=head1 THE THREE SHARED DRBG INSTANCES + +Currently, there are three shared DRBG instances, +the <master>, <public>, and <private> DRBG. +While the <master> DRBG is a single global instance, the <public> and <private> +DRBG are created per thread and accessed through thread-local storage. + +By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use +the thread-local <public> and <private> DRBG instance, respectively. + +=head2 The <master> DRBG instance + +The <master> DRBG is not used directly by the application, only for reseeding +the two other two DRBG instances. It reseeds itself by obtaining randomness +either from os entropy sources or by consuming randomness which was added +previously by L<RAND_add(3)>. + +=head2 The <public> DRBG instance + +This instance is used per default by L<RAND_bytes(3)>. + +=head2 The <private> DRBG instance + +This instance is used per default by L<RAND_priv_bytes(3)> + + +=head1 LOCKING + +The <master> DRBG is intended to be accessed concurrently for reseeding +by its child DRBG instances. The necessary locking is done internally. +It is I<not> thread-safe to access the <master> DRBG directly via the +RAND_DRBG interface. +The <public> and <private> DRBG are thread-local, i.e. there is an +instance of each per thread. So they can safely be accessed without +locking via the RAND_DRBG interface. + +Pointers to these DRBG instances can be obtained using +RAND_DRBG_get0_master(), +RAND_DRBG_get0_public(), and +RAND_DRBG_get0_private(), respectively. +Note that it is not allowed to store a pointer to one of the thread-local +DRBG instances in a variable or other memory location where it will be +accessed and used by multiple threads. + +All other DRBG instances created by an application don't support locking, +because they are intended to be used by a single thread. +Instead of accessing a single DRBG instance concurrently from different +threads, it is recommended to instantiate a separate DRBG instance per +thread. Using the <master> DRBG as entropy source for multiple DRBG +instances on different threads is thread-safe, because the DRBG instance +will lock the <master> DRBG automatically for obtaining random input. + +=head1 THE OVERALL PICTURE + +The following picture gives an overview over how the DRBG instances work +together and are being used. + + +--------------------+ + | os entropy sources | + +--------------------+ + | + v +-----------------------------+ + RAND_add() ==> <master> <-| shared DRBG (with locking) | + / \ +-----------------------------+ + / \ +---------------------------+ + <public> <private> <- | per-thread DRBG instances | + | | +---------------------------+ + v v + RAND_bytes() RAND_priv_bytes() + | ^ + | | + +------------------+ +------------------------------------+ + | general purpose | | used for secrets like session keys | + | random generator | | and private keys for certificates | + +------------------+ +------------------------------------+ + + +The usual way to obtain random bytes is to call RAND_bytes(...) or +RAND_priv_bytes(...). These calls are roughly equivalent to calling +RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...), +respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method +wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual +request for random data. + +=head1 RESEEDING + +A DRBG instance seeds itself automatically, pulling random input from +its entropy source. The entropy source can be either a trusted operating +system entropy source, or another DRBG with access to such a source. + +Automatic reseeding occurs after a predefined number of generate requests. +The selection of the trusted entropy sources is configured at build +time using the --with-rand-seed option. The following sections explain +the reseeding process in more detail. + +=head2 Automatic Reseeding + +Before satisfying a generate request (L<RAND_DRBG_generate(3)>), the DRBG +reseeds itself automatically, if one of the following conditions holds: + +- the DRBG was not instantiated (=seeded) yet or has been uninstantiated. + +- the number of generate requests since the last reseeding exceeds a +certain threshold, the so called I<reseed_interval>. +This behaviour can be disabled by setting the I<reseed_interval> to 0. + +- the time elapsed since the last reseeding exceeds a certain time +interval, the so called I<reseed_time_interval>. +This can be disabled by setting the I<reseed_time_interval> to 0. + +- the DRBG is in an error state. + +B<Note>: An error state is entered if the entropy source fails while +the DRBG is seeding or reseeding. +The last case ensures that the DRBG automatically recovers +from the error as soon as the entropy source is available again. + +=head2 Manual Reseeding + +In addition to automatic reseeding, the caller can request an immediate +reseeding of the DRBG with fresh entropy by setting the +I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>. + +The document [NIST SP 800-90C] describes prediction resistance requests +in detail and imposes strict conditions on the entropy sources that are +approved for providing prediction resistance. +Since the default DRBG implementation does not have access to such an approved +entropy source, a request for prediction resistance will currently always fail. +In other words, prediction resistance is currently not supported yet by the DRBG. + + +For the three shared DRBGs (and only for these) there is another way to +reseed them manually: +If L<RAND_add(3)> is called with a positive I<randomness> argument +(or L<RAND_seed(3)>), then this will immediately reseed the <master> DRBG. +The <public> and <private> DRBG will detect this on their next generate +call and reseed, pulling randomness from <master>. + +The last feature has been added to support the common practice used with +previous OpenSSL versions to call RAND_add() before calling RAND_bytes(). + + +=head2 Entropy Input vs. Additional Data + +The DRBG distinguishes two different types of random input: I<entropy>, +which comes from a trusted source, and I<additional input>', +which can optionally be added by the user and is considered untrusted. +It is possible to add I<additional input> not only during reseeding, +but also for every generate request. +This is in fact done automatically by L<RAND_DRBG_bytes(3)>. + + +=head2 Configuring the Random Seed Source + +In most cases OpenSSL will automatically choose a suitable seed source +for automatically seeding and reseeding its <master> DRBG. In some cases +however, it will be necessary to explicitly specify a seed source during +configuration, using the --with-rand-seed option. For more information, +see the INSTALL instructions. There are also operating systems where no +seed source is available and automatic reseeding is disabled by default. + +The following two sections describe the reseeding process of the master +DRBG, depending on whether automatic reseeding is available or not. + + +=head2 Reseeding the master DRBG with automatic seeding enabled + +Calling RAND_poll() or RAND_add() is not necessary, because the DRBG +pulls the necessary entropy from its source automatically. +However, both calls are permitted, and do reseed the RNG. + +RAND_add() can be used to add both kinds of random input, depending on the +value of the B<randomness> argument: + +=over 4 + +=item randomness == 0: + +The random bytes are mixed as additional input into the current state of +the DRBG. +Mixing in additional input is not considered a full reseeding, hence the +reseed counter is not reset. + + +=item randomness > 0: + +The random bytes are used as entropy input for a full reseeding +(resp. reinstantiation) if the DRBG is instantiated +(resp. uninstantiated or in an error state). +The number of random bits required for reseeding is determined by the +security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). +It is possible to provide less randomness than required. +In this case the missing randomness will be obtained by pulling random input +from the trusted entropy sources. + +=back + +=head2 Reseeding the master DRBG with automatic seeding disabled + +Calling RAND_poll() will always fail. + +RAND_add() needs to be called for initial seeding and periodic reseeding. +At least 48 bytes (384 bits) of randomness have to be provided, otherwise +the (re-)seeding of the DRBG will fail. This corresponds to one and a half +times the security strength of the DRBG. The extra half is used for the +nonce during instantiation. + +More precisely, the number of bytes needed for seeding depend on the +I<security strength> of the DRBG, which is set to 256 by default. + +=head1 SEE ALSO + +L<RAND_DRBG_bytes(3)>, +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG_reseed(3)>, +L<RAND_DRBG_get0_master(3)>, +L<RAND_DRBG_get0_public(3)>, +L<RAND_DRBG_get0_private(3)>, +L<RAND_DRBG_set_reseed_interval(3)>, +L<RAND_DRBG_set_reseed_time_interval(3)>, +L<RAND_DRBG_set_reseed_defaults(3)>, +L<RAND(7)>, + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/deps/openssl/openssl/doc/man7/RSA-PSS.pod b/deps/openssl/openssl/doc/man7/RSA-PSS.pod new file mode 100644 index 0000000000..29775d8621 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/RSA-PSS.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +RSA-PSS - EVP_PKEY RSA-PSS algorithm support + +=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. + +=head2 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. + +=head2 Key Generation + +By default no parameter restrictions are placed on the generated key. + +=head1 NOTES + +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 CONFORMING TO + +RFC 4055 + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_set_rsa_pss_keygen_md(3)>, +L<EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3)>, +L<EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/deps/openssl/openssl/doc/man7/SM2.pod b/deps/openssl/openssl/doc/man7/SM2.pod new file mode 100644 index 0000000000..029dc736cb --- /dev/null +++ b/deps/openssl/openssl/doc/man7/SM2.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +SM2 - Chinese SM2 signature and encryption algorithm support + +=head1 DESCRIPTION + +The B<SM2> algorithm was first defined by the Chinese national standard GM/T +0003-2012 and was later standardized by ISO as ISO/IEC 14888. B<SM2> is actually +an elliptic curve based algorithm. The current implementation in OpenSSL supports +both signature and encryption schemes via the EVP interface. + +When doing the B<SM2> signature algorithm, it requires a distinguishing identifier +to form the message prefix which is hashed before the real message is hashed. + +=head1 NOTES + +B<SM2> signatures can be generated by using the 'DigestSign' series of APIs, for +instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal(). +Ditto for the verification process by calling the 'DigestVerify' series of APIs. + +There are several special steps that need to be done before computing an B<SM2> +signature. + +The B<EVP_PKEY> structure will default to using ECDSA for signatures when it is +created. It should be set to B<EVP_PKEY_SM2> by calling: + + EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); + +Then an ID should be set by calling: + + EVP_PKEY_CTX_set1_id(pctx, id, id_len); + +When calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, a +pre-allocated B<EVP_PKEY_CTX> should be assigned to the B<EVP_MD_CTX>. This is +done by calling: + + EVP_MD_CTX_set_pkey_ctx(mctx, pctx); + +And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit() +or EVP_DigestVerifyInit() in such a scenario. + +=head1 EXAMPLE + +This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify +a message with the SM2 signature algorithm and the SM3 hash algorithm: + + #include <openssl/evp.h> + + /* obtain an EVP_PKEY using whatever methods... */ + EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); + mctx = EVP_MD_CTX_new(); + pctx = EVP_PKEY_CTX_new(pkey, NULL); + EVP_PKEY_CTX_set1_id(pctx, id, id_len); + EVP_MD_CTX_set_pkey_ctx(mctx, pctx);; + EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); + EVP_DigestVerifyUpdate(mctx, msg, msg_len); + EVP_DigestVerifyFinal(mctx, sig, sig_len) + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_set_alias_type(3)>, +L<EVP_DigestSignInit(3)>, +L<EVP_DigestVerifyInit(3)>, +L<EVP_PKEY_CTX_set1_id(3)>, +L<EVP_MD_CTX_set_pkey_ctx(3)> + +=head1 COPYRIGHT + +Copyright 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 diff --git a/deps/openssl/openssl/doc/man7/X25519.pod b/deps/openssl/openssl/doc/man7/X25519.pod new file mode 100644 index 0000000000..7cb6ff6b3b --- /dev/null +++ b/deps/openssl/openssl/doc/man7/X25519.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +X25519, +X448 +- EVP_PKEY X25519 and X448 support + +=head1 DESCRIPTION + +The B<X25519> and B<X448> EVP_PKEY implementation supports key generation and +key derivation using B<X25519> and B<X448>. 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); + +For the B<X448> algorithm a context can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL); + +X25519 or X448 private keys can be set directly using +L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file +using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. + +X25519 or X448 public keys can be set directly using +L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo +structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function). + +=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> and B<X448>. + +=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-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 diff --git a/deps/openssl/openssl/doc/man7/bio.pod b/deps/openssl/openssl/doc/man7/bio.pod new file mode 100644 index 0000000000..45ef2f7704 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/bio.pod @@ -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 + diff --git a/deps/openssl/openssl/doc/man7/crypto.pod b/deps/openssl/openssl/doc/man7/crypto.pod new file mode 100644 index 0000000000..e08c5c8aec --- /dev/null +++ b/deps/openssl/openssl/doc/man7/crypto.pod @@ -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 diff --git a/deps/openssl/openssl/doc/man7/ct.pod b/deps/openssl/openssl/doc/man7/ct.pod new file mode 100644 index 0000000000..355204d2a6 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/ct.pod @@ -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 diff --git a/deps/openssl/openssl/doc/man7/des_modes.pod b/deps/openssl/openssl/doc/man7/des_modes.pod new file mode 100644 index 0000000000..f7415d77f4 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/des_modes.pod @@ -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 diff --git a/deps/openssl/openssl/doc/man7/evp.pod b/deps/openssl/openssl/doc/man7/evp.pod new file mode 100644 index 0000000000..e493dacd23 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/evp.pod @@ -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 diff --git a/deps/openssl/openssl/doc/man7/ossl_store-file.pod b/deps/openssl/openssl/doc/man7/ossl_store-file.pod new file mode 100644 index 0000000000..996043b0fb --- /dev/null +++ b/deps/openssl/openssl/doc/man7/ossl_store-file.pod @@ -0,0 +1,71 @@ +=pod + +=begin comment + +This is a recommended way to describe OSSL_STORE loaders, +"ossl_store-{name}", where {name} is replaced with the name of the +scheme it implements, in man section 7. + +=end comment + +=head1 NAME + +ossl_store-file - The store 'file' scheme loader + +=head1 SYNOPSIS + +=for comment generic + +#include <openssl/store.h> + +=head1 DESCRIPTION + +Support for the 'file' scheme is 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 NOTES + +When needed, the 'file' scheme loader will require a pass phrase by +using the C<UI_METHOD> that was passed via OSSL_STORE_open(). +This pass phrase is expected to be UTF-8 encoded, anything else will +give an undefined result. +The files made accessible through this loader are expected to be +standard compliant with regards to pass phrase encoding. +Files that aren't should be re-generated with a correctly encoded pass +phrase. +See L<passphrase-encoding(7)> for more information. + +=head1 SEE ALSO + +L<ossl_store(7)>, L<passphrase-encoding(7)> + +=head1 COPYRIGHT + +Copyright 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 diff --git a/deps/openssl/openssl/doc/man7/ossl_store.pod b/deps/openssl/openssl/doc/man7/ossl_store.pod new file mode 100644 index 0000000000..6e75abd314 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/ossl_store.pod @@ -0,0 +1,87 @@ +=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. + +Support for the 'file' scheme is built into C<libcrypto>. +See L<ossl_store-file(7)> for more information. + +=head2 UI_METHOD and pass phrases + +The B<OSS_STORE> API does nothing to enforce any specific format or +encoding on the pass phrase that the B<UI_METHOD> provides. However, +the pass phrase is expected to be UTF-8 encoded. The result of any +other encoding is undefined. + +=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 diff --git a/deps/openssl/openssl/doc/man7/passphrase-encoding.pod b/deps/openssl/openssl/doc/man7/passphrase-encoding.pod new file mode 100644 index 0000000000..6810844526 --- /dev/null +++ b/deps/openssl/openssl/doc/man7/passphrase-encoding.pod @@ -0,0 +1,180 @@ +=pod + +=encoding utf8 + +=head1 NAME + +passphrase-encoding +- How diverse parts of OpenSSL treat pass phrases character encoding + +=head1 DESCRIPTION + +In a modern world with all sorts of character encodings, the treatment of pass +phrases has become increasingly complex. +This manual page attempts to give an overview over how this problem is +currently addressed in different parts of the OpenSSL library. + +=head2 The general case + +The OpenSSL library doesn't treat pass phrases in any special way as a general +rule, and trusts the application or user to choose a suitable character set +and stick to that throughout the lifetime of affected objects. +This means that for an object that was encrypted using a pass phrase encoded in +ISO-8859-1, that object needs to be decrypted using a pass phrase encoded in +ISO-8859-1. +Using the wrong encoding is expected to cause a decryption failure. + +=head2 PKCS#12 + +PKCS#12 is a bit different regarding pass phrase encoding. +The standard stipulates that the pass phrase shall be encoded as an ASN.1 +BMPString, which consists of the code points of the basic multilingual plane, +encoded in big endian (UCS-2 BE). + +OpenSSL tries to adapt to this requirements in one of the following manners: + +=over 4 + +=item 1. + +Treats the received pass phrase as UTF-8 encoded and tries to re-encode it to +UTF-16 (which is the same as UCS-2 for characters U+0000 to U+D7FF and U+E000 +to U+FFFF, but becomes an expansion for any other character), or failing that, +proceeds with step 2. + +=item 2. + +Assumes that the pass phrase is encoded in ASCII or ISO-8859-1 and +opportunistically prepends each byte with a zero byte to obtain the UCS-2 +encoding of the characters, which it stores as a BMPString. + +Note that since there is no check of your locale, this may produce UCS-2 / +UTF-16 characters that do not correspond to the original pass phrase characters +for other character sets, such as any ISO-8859-X encoding other than +ISO-8859-1 (or for Windows, CP 1252 with exception for the extra "graphical" +characters in the 0x80-0x9F range). + +=back + +OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why +OpenSSL still does this, to be able to read files produced with older versions. + +It should be noted that this approach isn't entirely fault free. + +A pass phrase encoded in ISO-8859-2 could very well have a sequence such as +0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE" +and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO-8859-2 encoding), but would +be misinterpreted as the perfectly valid UTF-8 encoded code point U+00EF (LATIN +SMALL LETTER I WITH DIARESIS) I<if the pass phrase doesn't contain anything that +would be invalid UTF-8>. +A pass phrase that contains this kind of byte sequence will give a different +outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0. + + 0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0 + 0x00 0xEF # OpenSSL 1.1.0 and newer + +On the same accord, anything encoded in UTF-8 that was given to OpenSSL older +than 1.1.0 was misinterpreted as ISO-8859-1 sequences. + +=head2 OSSL_STORE + +L<ossl_store(7)> acts as a general interface to access all kinds of objects, +potentially protected with a pass phrase, a PIN or something else. +This API stipulates that pass phrases should be UTF-8 encoded, and that any +other pass phrase encoding may give undefined results. +This API relies on the application to ensure UTF-8 encoding, and doesn't check +that this is the case, so what it gets, it will also pass to the underlying +loader. + +=head1 RECOMMENDATIONS + +This section assumes that you know what pass phrase was used for encryption, +but that it may have been encoded in a different character encoding than the +one used by your current input method. +For example, the pass phrase may have been used at a time when your default +encoding was ISO-8859-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 +0xEF 0x76 0x65), and you're now in an environment where your default encoding +is UTF-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76 +0x65). +Whenever it's mentioned that you should use a certain character encoding, it +should be understood that you either change the input method to use the +mentioned encoding when you type in your pass phrase, or use some suitable tool +to convert your pass phrase from your default encoding to the target encoding. + +Also note that the sub-sections below discuss human readable pass phrases. +This is particularly relevant for PKCS#12 objects, where human readable pass +phrases are assumed. +For other objects, it's as legitimate to use any byte sequence (such as a +sequence of bytes from `/dev/urandom` that's been saved away), which makes any +character encoding discussion irrelevant; in such cases, simply use the same +byte sequence as it is. + +=head2 Creating new objects + +For creating new pass phrase protected objects, make sure the pass phrase is +encoded using UTF-8. +This is default on most modern Unixes, but may involve an effort on other +platforms. +Specifically for Windows, setting the environment variable +C<OPENSSL_WIN32_UTF8> will have anything entered on [Windows] console prompt +converted to UTF-8 (command line and separately prompted pass phrases alike). + +=head2 Opening existing objects + +For opening pass phrase protected objects where you know what character +encoding was used for the encryption pass phrase, make sure to use the same +encoding again. + +For opening pass phrase protected objects where the character encoding that was +used is unknown, or where the producing application is unknown, try one of the +following: + +=over 4 + +=item 1. + +Try the pass phrase that you have as it is in the character encoding of your +environment. +It's possible that its byte sequence is exactly right. + +=item 2. + +Convert the pass phrase to UTF-8 and try with the result. +Specifically with PKCS#12, this should open up any object that was created +according to the specification. + +=item 3. + +Do a naïve (i.e. purely mathematical) ISO-8859-1 to UTF-8 conversion and try +with the result. +This differs from the previous attempt because ISO-8859-1 maps directly to +U+0000 to U+00FF, which other non-UTF-8 character sets do not. + +This also takes care of the case when a UTF-8 encoded string was used with +OpenSSL older than 1.1.0. +(for example, C<ï>, which is 0xC3 0xAF when encoded in UTF-8, would become 0xC3 +0x83 0xC2 0xAF when re-encoded in the naïve manner. +The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the +erroneous/non-compliant encoding used by OpenSSL older than 1.1.0) + +=back + +=head1 SEE ALSO + +L<evp(7)>, +L<ossl_store(7)>, +L<EVP_BytesToKey(3)>, L<EVP_DecryptInit(3)>, +L<PEM_do_header(3)>, +L<PKCS12_parse(3)>, L<PKCS12_newpass(3)>, +L<d2i_PKCS8PrivateKey_bio(3)> + +=head1 COPYRIGHT + +Copyright 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 diff --git a/deps/openssl/openssl/doc/man7/scrypt.pod b/deps/openssl/openssl/doc/man7/scrypt.pod new file mode 100644 index 0000000000..94ff3ab53f --- /dev/null +++ b/deps/openssl/openssl/doc/man7/scrypt.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +scrypt - EVP_PKEY scrypt KDF support + +=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. + +=head1 NOTES + +A context for scrypt can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_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 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_set1_scrypt_salt(3)>, +L<EVP_PKEY_CTX_set_scrypt_N(3)>, +L<EVP_PKEY_CTX_set_scrypt_r(3)>, +L<EVP_PKEY_CTX_set_scrypt_p(3)>, +L<EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/deps/openssl/openssl/doc/man7/ssl.pod b/deps/openssl/openssl/doc/man7/ssl.pod new file mode 100644 index 0000000000..d439860b5b --- /dev/null +++ b/deps/openssl/openssl/doc/man7/ssl.pod @@ -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. + +=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. +Must be used to support the TLSv1.3 protocol. + +=item const SSL_METHOD *B<TLS_server_method>(void); + +Constructor for the I<version-flexible> SSL_METHOD structure for servers. +Must be used to support the TLSv1.3 protocol. + +=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 int B<SSL_CTX_use_cert_and_key>(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); + +=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 size); + +=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_use_cert_and_key>(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); + +=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> were 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 diff --git a/deps/openssl/openssl/doc/man7/x509.pod b/deps/openssl/openssl/doc/man7/x509.pod new file mode 100644 index 0000000000..065dcb14fb --- /dev/null +++ b/deps/openssl/openssl/doc/man7/x509.pod @@ -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 |