• NAME
• DESCRIPTION
• NOTES
• EXAMPLES
• SEE ALSO
• COPYRIGHT

NAME

Ed25519, Ed448 - EVP_PKEY Ed25519 and Ed448 support

DESCRIPTION

The Ed25519 and Ed448 EVP_PKEY implementation supports key generation, one-shot digest sign and digest verify using PureEdDSA and Ed25519 or Ed448 (see RFC8032). It has associated private and public key formats compatible with RFC 8410.

No additional parameters can be set during key generation, one-shot signing or verification. In particular, because PureEdDSA is used, a digest must NOT be specified when signing or verifying.

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 type parameter MUST be set to 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 Ed25519 algorithm can be obtained by calling:

 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);

For the 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 EVP_PKEY_new_raw_private_key(3) or loaded from a PKCS#8 private key file using 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 EVP_PKEY_new_raw_public_key(3) or loaded from a SubjectPublicKeyInfo structure in a PEM file using PEM_read_bio_PUBKEY(3) (or similar function).

Ed25519 and Ed448 can be tested within speed(1) application since version 1.1.1. Valid algorithm names are ed25519, ed448 and eddsa. If eddsa is specified, then both Ed25519 and Ed448 are benchmarked.

EXAMPLES

This example generates an 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);

SEE ALSO

EVP_PKEY_CTX_new(3), EVP_PKEY_keygen(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3),

COPYRIGHT

Copyright 2017-2020 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
  • Disclaimer
  • Typical Use Cases
• CHAINING
• THE THREE SHARED DRBG INSTANCES
  • The <master> DRBG instance
  • The <public> DRBG instance
  • The <private> DRBG instance
• LOCKING
• THE OVERALL PICTURE
• RESEEDING
  • Automatic Reseeding
  • Manual Reseeding
  • Entropy Input vs. Additional Data
  • Configuring the Random Seed Source
  • Reseeding the master DRBG with automatic seeding enabled
  • Reseeding the master DRBG with automatic seeding disabled
• SEE ALSO
• COPYRIGHT

NAME

RAND_DRBG - the deterministic random bit generator

SYNOPSIS

 #include <openssl/rand_drbg.h>

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.

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 RAND_bytes(3) or RAND_priv_bytes(3), see also RAND(7).

Typical Use Cases

Typical examples for such special use cases are the following:

• 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).

• You need to integrate a previously unsupported entropy source.

• You need to change the default settings of the standard OpenSSL RAND implementation to meet specific requirements.

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 parent DRBG, the other instance the 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.

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 RAND_bytes(3) and RAND_priv_bytes(3) use the thread-local <public> and <private> DRBG instance, respectively.

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 RAND_add(3).

The <public> DRBG instance

This instance is used per default by RAND_bytes(3).

The <private> DRBG instance

This instance is used per default by RAND_priv_bytes(3)

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 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.

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 RAND_DRBG_bytes(3) is a convenience method wrapping the RAND_DRBG_generate(3) function, which serves the actual request for random data.

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.

Automatic Reseeding

Before satisfying a generate request (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 reseed_interval. This behaviour can be disabled by setting the reseed_interval to 0.

- the time elapsed since the last reseeding exceeds a certain time interval, the so called reseed_time_interval. This can be disabled by setting the reseed_time_interval to 0.

- the DRBG is in an error state.

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.

Manual Reseeding

In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG with fresh entropy by setting the prediction resistance parameter to 1 when calling 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 RAND_add(3) is called with a positive randomness argument (or 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().

Entropy Input vs. Additional Data

The DRBG distinguishes two different types of random input: entropy, which comes from a trusted source, and additional input', which can optionally be added by the user and is considered untrusted. It is possible to add additional input not only during reseeding, but also for every generate request. This is in fact done automatically by RAND_DRBG_bytes(3).

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.

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 randomness argument:

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.

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.

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 security strength of the DRBG, which is set to 256 by default.

SEE ALSO

RAND_DRBG_bytes(3), RAND_DRBG_generate(3), RAND_DRBG_reseed(3), RAND_DRBG_get0_master(3), RAND_DRBG_get0_public(3), RAND_DRBG_get0_private(3), RAND_DRBG_set_reseed_interval(3), RAND_DRBG_set_reseed_time_interval(3), RAND_DRBG_set_reseed_defaults(3), RAND(7),

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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• SEE ALSO
• COPYRIGHT

NAME

evp - high-level cryptographic functions

SYNOPSIS

 #include <openssl/evp.h>

DESCRIPTION

The EVP library provides a high-level interface to cryptographic functions.

The EVP_SealXXX and EVP_OpenXXX functions provide public key encryption and decryption to implement digital "envelopes".

The EVP_DigestSignXXX and EVP_DigestVerifyXXX functions implement digital signatures and Message Authentication Codes (MACs). Also see the older EVP_SignXXX and EVP_VerifyXXX functions.

Symmetric encryption is available with the EVP_EncryptXXX functions. The EVP_DigestXXX functions provide message digests.

The EVP_PKEYXXX functions provide a high-level interface to asymmetric algorithms. To create a new EVP_PKEY see EVP_PKEY_new(3). EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions described on the EVP_PKEY_set1_RSA(3) page, or new keys can be generated using EVP_PKEY_keygen(3). EVP_PKEYs can be compared using EVP_PKEY_cmp(3), or printed using EVP_PKEY_print_private(3).

The EVP_PKEY functions support the full range of asymmetric algorithm operations:

For key agreement see EVP_PKEY_derive(3)

For signing and verifying see EVP_PKEY_sign(3), EVP_PKEY_verify(3) and 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 EVP_DigestSignInit(3) functions for this purpose.

For encryption and decryption see EVP_PKEY_encrypt(3) and 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 EVP_SealInit(3) and EVP_OpenInit(3) functions.

The 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 EVP_EncodeXXX and EVP_DecodeXXX 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.

SEE ALSO

EVP_DigestInit(3), EVP_EncryptInit(3), EVP_OpenInit(3), EVP_SealInit(3), EVP_DigestSignInit(3), EVP_SignInit(3), EVP_VerifyInit(3), EVP_EncodeInit(3), EVP_PKEY_new(3), EVP_PKEY_set1_RSA(3), EVP_PKEY_keygen(3), EVP_PKEY_print_private(3), EVP_PKEY_decrypt(3), EVP_PKEY_encrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3), EVP_BytesToKey(3), ENGINE_by_id(3)

COPYRIGHT

Copyright 2000-2020 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• NOTES
• RETURN VALUES
• SEE ALSO
• COPYRIGHT

NAME

crypto - OpenSSL cryptographic library

SYNOPSIS

See the individual manual pages for details.

DESCRIPTION

The OpenSSL 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.

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.

NOTES

Some of the newer functions follow a naming convention using the numbers 0 and 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 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 crl would be freed but rev would not.

The 1 function uses a copy of the supplied structure pointer (or in some cases increases its link count) in the parent and so both (x and obj above) should be freed up.

RETURN VALUES

See the individual manual pages for details.

SEE ALSO

openssl(1), ssl(7)

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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
• NOTES
• EXAMPLES
• SEE ALSO
• COPYRIGHT

NAME

X25519, X448 - EVP_PKEY X25519 and X448 support

DESCRIPTION

The X25519 and X448 EVP_PKEY implementation supports key generation and key derivation using X25519 and X448. It has associated private and public key formats compatible with RFC 8410.

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.

NOTES

A context for the X25519 algorithm can be obtained by calling:

 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);

For the 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 EVP_PKEY_new_raw_private_key(3) or loaded from a PKCS#8 private key file using 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 EVP_PKEY_new_raw_public_key(3) or loaded from a SubjectPublicKeyInfo structure in a PEM file using PEM_read_bio_PUBKEY(3) (or similar function).

EXAMPLES

This example generates an 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 EVP_PKEY_derive(3) can be used with X25519 and X448.

SEE ALSO

EVP_PKEY_CTX_new(3), EVP_PKEY_keygen(3), EVP_PKEY_derive(3), EVP_PKEY_derive_set_peer(3)

COPYRIGHT

Copyright 2017-2020 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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
• NOTES
• EXAMPLES
• SEE ALSO
• COPYRIGHT

NAME

SM2 - Chinese SM2 signature and encryption algorithm support

DESCRIPTION

The SM2 algorithm was first defined by the Chinese national standard GM/T 0003-2012 and was later standardized by ISO as ISO/IEC 14888. 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 SM2 signature algorithm, it requires a distinguishing identifier to form the message prefix which is hashed before the real message is hashed.

NOTES

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 SM2 signature.

The EVP_PKEY structure will default to using ECDSA for signatures when it is created. It should be set to 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 preallocated EVP_PKEY_CTX should be assigned to the 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 pctx parameter to EVP_DigestSignInit() or EVP_DigestVerifyInit() in such a scenario.

EXAMPLES

This example demonstrates the calling sequence for using an 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)

SEE ALSO

EVP_PKEY_CTX_new(3), EVP_PKEY_set_alias_type(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_CTX_set1_id(3), EVP_MD_CTX_set_pkey_ctx(3)

COPYRIGHT

Copyright 2018-2020 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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
• OVERVIEW
  • Electronic Codebook Mode (ECB)
  • Cipher Block Chaining Mode (CBC)
  • Cipher Feedback Mode (CFB)
  • Output Feedback Mode (OFB)
  • Triple ECB Mode
  • Triple CBC Mode
• NOTES
• SEE ALSO
• COPYRIGHT

NAME

des_modes - the variants of DES and other crypto algorithms of OpenSSL

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.

OVERVIEW

Electronic Codebook Mode (ECB)

Normally, this is found as the function algorithm_ecb_encrypt().

• 64 bits are enciphered at a time.

• The order of the blocks can be rearranged without detection.

• The same plaintext block always produces the same ciphertext block (for the same key) making it vulnerable to a 'dictionary attack'.

• An error will only affect one ciphertext block.

Cipher Block Chaining Mode (CBC)

Normally, this is found as the function 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.

• a multiple of 64 bits are enciphered at a time.

• The CBC mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.

• The chaining operation makes the ciphertext blocks dependent on the current and all preceding plaintext blocks and therefore blocks can not be rearranged.

• The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.

• An error will affect the current and the following ciphertext blocks.

Cipher Feedback Mode (CFB)

Normally, this is found as the function algorithm_cfb_encrypt().

• a number of bits (j) <= 64 are enciphered at a time.

• The CFB mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.

• 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.

• The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.

• The strength of the CFB mode depends on the size of k (maximal if j == k). In my implementation this is always the case.

• 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.

• Only multiples of j bits can be enciphered.

• An error will affect the current and the following ciphertext variables.

Output Feedback Mode (OFB)

Normally, this is found as the function algorithm_ofb_encrypt().

• a number of bits (j) <= 64 are enciphered at a time.

• 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.

• The absence of chaining makes the OFB more vulnerable to specific attacks.

• The use of different start variables values prevents the same plaintext enciphering to the same ciphertext, by producing different key streams.

• 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.

• Only multiples of j bits can be enciphered.

• 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.

• 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.

• 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.

Triple ECB Mode

Normally, this is found as the function algorithm_ecb3_encrypt().

• Encrypt with key1, decrypt with key2 and encrypt with key3 again.

• 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.

• If both keys are the same it is equivalent to encrypting once with just one key.

• 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.

• If all 3 keys are the same, this is effectively the same as normal ecb mode.

Triple CBC Mode

Normally, this is found as the function algorithm_ede3_cbc_encrypt().

• Encrypt with key1, decrypt with key2 and then encrypt with key3.

• As for CBC encryption but increases the key length to 168 bits with the same restrictions as for triple ecb mode.

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

SEE ALSO

BF_encrypt(3), DES_crypt(3)

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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
• NOTES
• EXAMPLES
• CONFORMING TO
• SEE ALSO
• COPYRIGHT

NAME

scrypt - EVP_PKEY scrypt KDF support

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.

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 EVP_PKEY_derive(3) function.

EXAMPLES

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);

CONFORMING TO

RFC 7914

SEE ALSO

EVP_PKEY_CTX_set1_scrypt_salt(3), EVP_PKEY_CTX_set_scrypt_N(3), EVP_PKEY_CTX_set_scrypt_r(3), EVP_PKEY_CTX_set_scrypt_p(3), EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3), EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

COPYRIGHT

Copyright 2017-2019 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• EXAMPLES
• SEE ALSO
• COPYRIGHT

NAME

bio - Basic I/O abstraction

SYNOPSIS

 #include <openssl/bio.h>

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 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_*();

EXAMPLES

Create a memory BIO:

 BIO *mem = BIO_new(BIO_s_mem());

SEE ALSO

BIO_ctrl(3), BIO_f_base64(3), BIO_f_buffer(3), BIO_f_cipher(3), BIO_f_md(3), BIO_f_null(3), BIO_f_ssl(3), BIO_find_type(3), BIO_new(3), BIO_new_bio_pair(3), BIO_push(3), BIO_read_ex(3), BIO_s_accept(3), BIO_s_bio(3), BIO_s_connect(3), BIO_s_fd(3), BIO_s_file(3), BIO_s_mem(3), BIO_s_null(3), BIO_s_socket(3), BIO_set_callback(3), BIO_should_retry(3)

COPYRIGHT

Copyright 2000-2019 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• SEE ALSO
• COPYRIGHT

NAME

x509 - X.509 certificate handling

SYNOPSIS

 #include <openssl/x509.h>

DESCRIPTION

An X.509 certificate is a structured grouping of information about an individual, a device, or anything one can imagine. An 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 attribute), 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.

X509_XXX, d2i_X509_XXX, and i2d_X509_XXX functions handle X.509 certificates, with some exceptions, shown below.

X509_CRL_XXX, d2i_X509_CRL_XXX, and i2d_X509_CRL_XXX functions handle X.509 CRLs.

X509_REQ_XXX, d2i_X509_REQ_XXX, and i2d_X509_REQ_XXX functions handle PKCS#10 certificate requests.

X509_NAME_XXX functions handle certificate names.

X509_ATTRIBUTE_XXX functions handle certificate attributes.

X509_EXTENSION_XXX functions handle certificate extensions.

SEE ALSO

X509_NAME_ENTRY_get_object(3), X509_NAME_add_entry_by_txt(3), X509_NAME_add_entry_by_NID(3), X509_NAME_print_ex(3), X509_NAME_new(3), d2i_X509(3), d2i_X509_ALGOR(3), d2i_X509_CRL(3), d2i_X509_NAME(3), d2i_X509_REQ(3), d2i_X509_SIG(3), X509v3(3), crypto(7)

COPYRIGHT

Copyright 2003-2021 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• DATA STRUCTURES
• HEADER FILES
• API FUNCTIONS
  • Dealing with Protocol Methods
  • Dealing with Ciphers
  • Dealing with Protocol Contexts
  • Dealing with Sessions
  • Dealing with Connections
• RETURN VALUES
• SEE ALSO
• HISTORY
• COPYRIGHT

NAME

ssl - OpenSSL SSL/TLS library

SYNOPSIS

See the individual manual pages for details.

DESCRIPTION

The OpenSSL 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 SSL_CTX object is created as a framework to establish TLS/SSL enabled connections (see 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 SSL object. After the SSL object has been created using SSL_new(3), SSL_set_fd(3) or SSL_set_bio(3) can be used to associate the network connection with the object.

When the TLS/SSL handshake is performed using SSL_accept(3) or SSL_connect(3) respectively. SSL_read_ex(3), SSL_read(3), SSL_write_ex(3) and SSL_write(3) are used to read and write data on the TLS/SSL connection. SSL_shutdown(3) can be used to shut down the TLS/SSL connection.

DATA STRUCTURES

Currently the OpenSSL ssl library functions deals with the following data structures:

SSL_METHOD (SSL Method)

This is a dispatch structure describing the internal ssl library methods/functions which implement the various protocol versions (SSLv3 TLSv1, ...). It's needed to create an SSL_CTX.

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 SSL_CTX basis and the actual ones used are then part of the SSL_SESSION.

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 SSL structures which are later created for the connections.

SSL_SESSION (SSL Session)

This is a structure containing the current TLS/SSL session details for a connection: SSL_CIPHERs, client and server certificates, keys, etc.

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.

HEADER FILES

Currently the OpenSSL ssl library provides the following C header files containing the prototypes for the data structures and functions:

ssl.h

This is the common header file for the SSL/TLS API. Include it into your program to make the API of the ssl library available. It internally includes both more private SSL headers and headers from the crypto library. Whenever you need hard-core details on the internals of the SSL API, look inside this header file.

ssl2.h

Unused. Present for backwards compatibility only.

ssl3.h

This is the sub header file dealing with the SSLv3 protocol only. Usually you don't have to include it explicitly because it's already included by ssl.h.

tls1.h

This is the sub header file dealing with the TLSv1 protocol only. Usually you don't have to include it explicitly because it's already included by ssl.h.

API FUNCTIONS

Currently the OpenSSL ssl library exports 214 API functions. They are documented in the following:

Dealing with Protocol Methods

Here we document the various API functions which deal with the SSL/TLS protocol methods defined in SSL_METHOD structures.

const SSL_METHOD *TLS_method(void);

Constructor for the version-flexible SSL_METHOD structure for clients, servers or both. See SSL_CTX_new(3) for details.

const SSL_METHOD *TLS_client_method(void);

Constructor for the version-flexible SSL_METHOD structure for clients. Must be used to support the TLSv1.3 protocol.

const SSL_METHOD *TLS_server_method(void);

Constructor for the version-flexible SSL_METHOD structure for servers. Must be used to support the TLSv1.3 protocol.

const SSL_METHOD *TLSv1_2_method(void);

Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both.

const SSL_METHOD *TLSv1_2_client_method(void);

Constructor for the TLSv1.2 SSL_METHOD structure for clients.

const SSL_METHOD *TLSv1_2_server_method(void);

Constructor for the TLSv1.2 SSL_METHOD structure for servers.

const SSL_METHOD *TLSv1_1_method(void);

Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both.

const SSL_METHOD *TLSv1_1_client_method(void);

Constructor for the TLSv1.1 SSL_METHOD structure for clients.

const SSL_METHOD *TLSv1_1_server_method(void);

Constructor for the TLSv1.1 SSL_METHOD structure for servers.

const SSL_METHOD *TLSv1_method(void);

Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both.

const SSL_METHOD *TLSv1_client_method(void);

Constructor for the TLSv1 SSL_METHOD structure for clients.

const SSL_METHOD *TLSv1_server_method(void);

Constructor for the TLSv1 SSL_METHOD structure for servers.

const SSL_METHOD *SSLv3_method(void);

Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both.

const SSL_METHOD *SSLv3_client_method(void);

Constructor for the SSLv3 SSL_METHOD structure for clients.

const SSL_METHOD *SSLv3_server_method(void);

Constructor for the SSLv3 SSL_METHOD structure for servers.

Dealing with Ciphers

Here we document the various API functions which deal with the SSL/TLS ciphers defined in SSL_CIPHER structures.

char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int len);

Write a string to buf (with a maximum size of len) containing a human readable description of cipher. Returns buf.

int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);

Determine the number of bits in cipher. Because of export crippled ciphers there are two bits: The bits the algorithm supports in general (stored to alg_bits) and the bits which are actually used (the return value).

const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);

Return the internal name of cipher as a string. These are the various strings defined by the SSL3_TXT_xxx and TLS1_TXT_xxx definitions in the header files.

const char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);

Returns a string like "SSLv3" or "TLSv1.2" which indicates the SSL/TLS protocol version to which cipher belongs (i.e. where it was defined in the specification the first time).

Dealing with Protocol Contexts

Here we document the various API functions which deal with the SSL/TLS protocol context defined in the SSL_CTX structure.

int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);

long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);

int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);

int SSL_CTX_check_private_key(const SSL_CTX *ctx);

long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, char *parg);

void SSL_CTX_flush_sessions(SSL_CTX *s, long t);

void SSL_CTX_free(SSL_CTX *a);

char *SSL_CTX_get_app_data(SSL_CTX *ctx);

X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx);

STACK *SSL_CTX_get_ciphers(const SSL_CTX *ctx);

STACK *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);

int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);

void SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);

char *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx);

int SSL_CTX_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))

void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);

int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);

void SSL_CTX_get_read_ahead(SSL_CTX *ctx);

int SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);

long SSL_CTX_get_timeout(const SSL_CTX *ctx);

int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);

int SSL_CTX_get_verify_mode(SSL_CTX *ctx);

int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, const char *CApath);

SSL_CTX *SSL_CTX_new(const SSL_METHOD *meth);

int SSL_CTX_up_ref(SSL_CTX *ctx);

int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);

int SSL_CTX_sess_accept(SSL_CTX *ctx);

int SSL_CTX_sess_accept_good(SSL_CTX *ctx);

int SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);

int SSL_CTX_sess_cache_full(SSL_CTX *ctx);

int SSL_CTX_sess_cb_hits(SSL_CTX *ctx);

int SSL_CTX_sess_connect(SSL_CTX *ctx);

int SSL_CTX_sess_connect_good(SSL_CTX *ctx);

int SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);

int SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);

SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);

int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);

void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);

int SSL_CTX_sess_hits(SSL_CTX *ctx);

int SSL_CTX_sess_misses(SSL_CTX *ctx);

int SSL_CTX_sess_number(SSL_CTX *ctx);

void SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, t);

void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));

void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));

void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));

int SSL_CTX_sess_timeouts(SSL_CTX *ctx);

LHASH *SSL_CTX_sessions(SSL_CTX *ctx);

int SSL_CTX_set_app_data(SSL_CTX *ctx, void *arg);

void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *cs);

void SSL_CTX_set1_cert_store(SSL_CTX *ctx, X509_STORE *cs);

void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(), char *arg)

int SSL_CTX_set_cipher_list(SSL_CTX *ctx, char *str);

void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK *list);

void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));

int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);

void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, int (*cb);(void))

void SSL_CTX_set_default_read_ahead(SSL_CTX *ctx, int m);

int 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.

int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx)

Use the default directory path to locate trusted CA certificates.

int SSL_CTX_set_default_verify_file(SSL_CTX *ctx)

Use the file path to locate trusted CA certificates.

int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, char *arg);

void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));

void 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));

void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);

unsigned long SSL_CTX_clear_options(SSL_CTX *ctx, unsigned long op);

unsigned long SSL_CTX_get_options(SSL_CTX *ctx);

unsigned long SSL_CTX_set_options(SSL_CTX *ctx, unsigned long op);

void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);

void SSL_CTX_set_read_ahead(SSL_CTX *ctx, int m);

void SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, int mode);

int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);

void SSL_CTX_set_timeout(SSL_CTX *ctx, long t);

long SSL_CTX_set_tmp_dh(SSL_CTX* ctx, DH *dh);

long SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, DH *(*cb)(void));

void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, int (*cb);(void))

int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);

int SSL_CTX_use_PrivateKey_ASN1(int type, SSL_CTX *ctx, unsigned char *d, long len);

int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);

int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);

int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);

int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);

int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);

int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);

int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);

int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);

X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx);

EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx);

void 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));

int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);

void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));

Dealing with Sessions

Here we document the various API functions which deal with the SSL/TLS sessions defined in the SSL_SESSION structures.

int SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b);

void SSL_SESSION_free(SSL_SESSION *ss);

char *SSL_SESSION_get_app_data(SSL_SESSION *s);

char *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx);

int SSL_SESSION_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))

long SSL_SESSION_get_time(const SSL_SESSION *s);

long SSL_SESSION_get_timeout(const SSL_SESSION *s);

unsigned long SSL_SESSION_hash(const SSL_SESSION *a);

SSL_SESSION *SSL_SESSION_new(void);

int SSL_SESSION_print(BIO *bp, const SSL_SESSION *x);

int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *x);

int SSL_SESSION_set_app_data(SSL_SESSION *s, char *a);

int SSL_SESSION_set_ex_data(SSL_SESSION *s, int idx, char *arg);

long SSL_SESSION_set_time(SSL_SESSION *s, long t);

long SSL_SESSION_set_timeout(SSL_SESSION *s, long t);

Dealing with Connections

Here we document the various API functions which deal with the SSL/TLS connection defined in the SSL structure.

int SSL_accept(SSL *ssl);

int SSL_add_dir_cert_subjects_to_stack(STACK *stack, const char *dir);

int SSL_add_file_cert_subjects_to_stack(STACK *stack, const char *file);

int SSL_add_client_CA(SSL *ssl, X509 *x);

char *SSL_alert_desc_string(int value);

char *SSL_alert_desc_string_long(int value);

char *SSL_alert_type_string(int value);

char *SSL_alert_type_string_long(int value);

int SSL_check_private_key(const SSL *ssl);

void SSL_clear(SSL *ssl);

long SSL_clear_num_renegotiations(SSL *ssl);

int SSL_connect(SSL *ssl);

int SSL_copy_session_id(SSL *t, const SSL *f);

Sets the session details for t to be the same as in f. Returns 1 on success or 0 on failure.

long SSL_ctrl(SSL *ssl, int cmd, long larg, char *parg);

int SSL_do_handshake(SSL *ssl);

SSL *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 same handle. It may be possible to use 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.

STACK *SSL_dup_CA_list(STACK *sk);

void SSL_free(SSL *ssl);

SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);

char *SSL_get_app_data(SSL *ssl);

X509 *SSL_get_certificate(const SSL *ssl);

const char *SSL_get_cipher(const SSL *ssl);

int SSL_is_dtls(const SSL *ssl);

int SSL_get_cipher_bits(const SSL *ssl, int *alg_bits);

char *SSL_get_cipher_list(const SSL *ssl, int n);

char *SSL_get_cipher_name(const SSL *ssl);

char *SSL_get_cipher_version(const SSL *ssl);

STACK *SSL_get_ciphers(const SSL *ssl);

STACK *SSL_get_client_CA_list(const SSL *ssl);

SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);

long SSL_get_default_timeout(const SSL *ssl);

int SSL_get_error(const SSL *ssl, int i);

char *SSL_get_ex_data(const SSL *ssl, int idx);

int SSL_get_ex_data_X509_STORE_CTX_idx(void);

int SSL_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))

int SSL_get_fd(const SSL *ssl);

void (*SSL_get_info_callback(const SSL *ssl);)()

int SSL_get_key_update_type(SSL *s);

STACK *SSL_get_peer_cert_chain(const SSL *ssl);

X509 *SSL_get_peer_certificate(const SSL *ssl);

const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);

EVP_PKEY *SSL_get_privatekey(const SSL *ssl);

int SSL_get_quiet_shutdown(const SSL *ssl);

BIO *SSL_get_rbio(const SSL *ssl);

int SSL_get_read_ahead(const SSL *ssl);

SSL_SESSION *SSL_get_session(const SSL *ssl);

char *SSL_get_shared_ciphers(const SSL *ssl, char *buf, int size);

int SSL_get_shutdown(const SSL *ssl);

const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);

int SSL_get_state(const SSL *ssl);

long SSL_get_time(const SSL *ssl);

long SSL_get_timeout(const SSL *ssl);

int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *)

int SSL_get_verify_mode(const SSL *ssl);

long SSL_get_verify_result(const SSL *ssl);

char *SSL_get_version(const SSL *ssl);

BIO *SSL_get_wbio(const SSL *ssl);

int SSL_in_accept_init(SSL *ssl);

int SSL_in_before(SSL *ssl);

int SSL_in_connect_init(SSL *ssl);

int SSL_in_init(SSL *ssl);

int SSL_is_init_finished(SSL *ssl);

int SSL_key_update(SSL *s, int updatetype);

STACK *SSL_load_client_CA_file(const char *file);

SSL *SSL_new(SSL_CTX *ctx);

int SSL_up_ref(SSL *s);

long SSL_num_renegotiations(SSL *ssl);

int SSL_peek(SSL *ssl, void *buf, int num);

int SSL_pending(const SSL *ssl);

int SSL_read(SSL *ssl, void *buf, int num);

int SSL_renegotiate(SSL *ssl);

char *SSL_rstate_string(SSL *ssl);

char *SSL_rstate_string_long(SSL *ssl);

long SSL_session_reused(SSL *ssl);

void SSL_set_accept_state(SSL *ssl);

void SSL_set_app_data(SSL *ssl, char *arg);

void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);

int SSL_set_cipher_list(SSL *ssl, char *str);

void SSL_set_client_CA_list(SSL *ssl, STACK *list);

void SSL_set_connect_state(SSL *ssl);

int SSL_set_ct_validation_callback(SSL *ssl, ssl_ct_validation_cb callback, void *arg);

int SSL_set_ex_data(SSL *ssl, int idx, char *arg);

int SSL_set_fd(SSL *ssl, int fd);

void SSL_set_info_callback(SSL *ssl, void (*cb);(void))

void 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));

void SSL_set_msg_callback_arg(SSL *ctx, void *arg);

unsigned long SSL_clear_options(SSL *ssl, unsigned long op);

unsigned long SSL_get_options(SSL *ssl);

unsigned long SSL_set_options(SSL *ssl, unsigned long op);

void SSL_set_quiet_shutdown(SSL *ssl, int mode);

void SSL_set_read_ahead(SSL *ssl, int yes);

int SSL_set_rfd(SSL *ssl, int fd);

int SSL_set_session(SSL *ssl, SSL_SESSION *session);

void SSL_set_shutdown(SSL *ssl, int mode);

int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *meth);

void SSL_set_time(SSL *ssl, long t);

void SSL_set_timeout(SSL *ssl, long t);

void SSL_set_verify(SSL *ssl, int mode, int (*callback);(void))

void SSL_set_verify_result(SSL *ssl, long arg);

int SSL_set_wfd(SSL *ssl, int fd);

int SSL_shutdown(SSL *ssl);

OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl);

Returns the current handshake state.

char *SSL_state_string(const SSL *ssl);

char *SSL_state_string_long(const SSL *ssl);

long SSL_total_renegotiations(SSL *ssl);

int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);

int SSL_use_PrivateKey_ASN1(int type, SSL *ssl, unsigned char *d, long len);

int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);

int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);

int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);

int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);

int SSL_use_certificate(SSL *ssl, X509 *x);

int SSL_use_certificate_ASN1(SSL *ssl, int len, unsigned char *d);

int SSL_use_certificate_file(SSL *ssl, const char *file, int type);

int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);

int SSL_version(const SSL *ssl);

int SSL_want(const SSL *ssl);

int SSL_want_nothing(const SSL *ssl);

int SSL_want_read(const SSL *ssl);

int SSL_want_write(const SSL *ssl);

int SSL_want_x509_lookup(const SSL *ssl);

int SSL_write(SSL *ssl, const void *buf, int num);

void 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));

int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);

void SSL_set_psk_server_callback(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));

const char *SSL_get_psk_identity_hint(SSL *ssl);

const char *SSL_get_psk_identity(SSL *ssl);

RETURN VALUES

See the individual manual pages for details.

SEE ALSO

openssl(1), crypto(7), CRYPTO_get_ex_new_index(3), SSL_accept(3), SSL_clear(3), SSL_connect(3), SSL_CIPHER_get_name(3), SSL_COMP_add_compression_method(3), SSL_CTX_add_extra_chain_cert(3), SSL_CTX_add_session(3), SSL_CTX_ctrl(3), SSL_CTX_flush_sessions(3), SSL_CTX_get_verify_mode(3), SSL_CTX_load_verify_locations(3) SSL_CTX_new(3), SSL_CTX_sess_number(3), SSL_CTX_sess_set_cache_size(3), SSL_CTX_sess_set_get_cb(3), SSL_CTX_sessions(3), SSL_CTX_set_cert_store(3), SSL_CTX_set_cert_verify_callback(3), SSL_CTX_set_cipher_list(3), SSL_CTX_set_client_CA_list(3), SSL_CTX_set_client_cert_cb(3), SSL_CTX_set_default_passwd_cb(3), SSL_CTX_set_generate_session_id(3), SSL_CTX_set_info_callback(3), SSL_CTX_set_max_cert_list(3), SSL_CTX_set_mode(3), SSL_CTX_set_msg_callback(3), SSL_CTX_set_options(3), SSL_CTX_set_quiet_shutdown(3), SSL_CTX_set_read_ahead(3), SSL_CTX_set_security_level(3), SSL_CTX_set_session_cache_mode(3), SSL_CTX_set_session_id_context(3), SSL_CTX_set_ssl_version(3), SSL_CTX_set_timeout(3), SSL_CTX_set_tmp_dh_callback(3), SSL_CTX_set_verify(3), SSL_CTX_use_certificate(3), SSL_alert_type_string(3), SSL_do_handshake(3), SSL_enable_ct(3), SSL_get_SSL_CTX(3), SSL_get_ciphers(3), SSL_get_client_CA_list(3), SSL_get_default_timeout(3), SSL_get_error(3), SSL_get_ex_data_X509_STORE_CTX_idx(3), SSL_get_fd(3), SSL_get_peer_cert_chain(3), SSL_get_rbio(3), SSL_get_session(3), SSL_get_verify_result(3), SSL_get_version(3), SSL_load_client_CA_file(3), SSL_new(3), SSL_pending(3), SSL_read_ex(3), SSL_read(3), SSL_rstate_string(3), SSL_session_reused(3), SSL_set_bio(3), SSL_set_connect_state(3), SSL_set_fd(3), SSL_set_session(3), SSL_set_shutdown(3), SSL_shutdown(3), SSL_state_string(3), SSL_want(3), SSL_write_ex(3), SSL_write(3), SSL_SESSION_free(3), SSL_SESSION_get_time(3), d2i_SSL_SESSION(3), SSL_CTX_set_psk_client_callback(3), SSL_CTX_use_psk_identity_hint(3), SSL_get_psk_identity(3), DTLSv1_listen(3)

HISTORY

SSLv2_client_method, SSLv2_server_method and SSLv2_method were removed in OpenSSL 1.1.0.

The return type of SSL_copy_session_id was changed from void to int in OpenSSL 1.1.0.

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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
• SEE ALSO
• COPYRIGHT

NAME

RAND - the OpenSSL random generator

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 RAND_bytes(3) to obtain random data. Having said that, there is one important rule to obey: Always check the error return value of RAND_bytes(3) and do not take randomness for granted. Although (re-)seeding is automatic, it can fail because no trusted random source is available or the trusted source(s) temporarily fail to provide sufficient random seed material. In this case the CSPRNG enters an error state and ceases to provide output, until it is able to recover from the error by reseeding itself. For more details on reseeding and error recovery, see RAND_DRBG(7).

For values that should remain secret, you can use 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:

• Replace the default RAND method by your own RAND method using RAND_set_rand_method(3).

• Modify the default settings of the OpenSSL RAND method by modifying the security parameters of the underlying DRBG, which is described in detail in RAND_DRBG(7).

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.

SEE ALSO

RAND_add(3), RAND_bytes(3), RAND_priv_bytes(3), RAND_get_rand_method(3), RAND_set_rand_method(3), RAND_OpenSSL(3), RAND_DRBG(7)

COPYRIGHT

Copyright 2018-2019 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• NOTES
• SEE ALSO
• COPYRIGHT

NAME

ossl_store-file - The store 'file' scheme loader

SYNOPSIS

#include <openssl/store.h>

DESCRIPTION

Support for the 'file' scheme is built into 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 '-----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).

NOTES

When needed, the 'file' scheme loader will require a pass phrase by using the 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 passphrase-encoding(7) for more information.

SEE ALSO

ossl_store(7), passphrase-encoding(7)

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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
  • General
  • URI schemes and loaders
  • UI_METHOD and pass phrases
• EXAMPLES
  • A generic call
• SEE ALSO
• COPYRIGHT

NAME

ossl_store - Store retrieval functions

SYNOPSIS

#include <openssl/store.h>

DESCRIPTION

General

A STORE is a layer of functionality to retrieve a number of supported objects from a repository of any kind, addressable as a filename 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 OSSL_STORE_INFO, from which an OpenSSL type can be retrieved.

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 libcrypto. See ossl_store-file(7) for more information.

UI_METHOD and pass phrases

The OSS_STORE API does nothing to enforce any specific format or encoding on the pass phrase that the UI_METHOD provides. However, the pass phrase is expected to be UTF-8 encoded. The result of any other encoding is undefined.

EXAMPLES

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_CERT:
         /* 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);

SEE ALSO

OSSL_STORE_INFO(3), OSSL_STORE_LOADER(3), OSSL_STORE_open(3), OSSL_STORE_expect(3), OSSL_STORE_SEARCH(3)

COPYRIGHT

Copyright 2016-2021 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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
  • Signing and Verification
  • Key Generation
• NOTES
• CONFORMING TO
• SEE ALSO
• COPYRIGHT

NAME

RSA-PSS - EVP_PKEY RSA-PSS algorithm support

DESCRIPTION

The 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 RSA algorithm but with some restrictions described below.

Signing and Verification

Signing and verification is similar to the 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.

Key Generation

By default no parameter restrictions are placed on the generated key.

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 id-RSASSA-PSS OID and the parameters field, if present, restricts the key parameters in the same way as the public key.

CONFORMING TO

RFC 4055

SEE ALSO

EVP_PKEY_CTX_set_rsa_pss_keygen_md(3), EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3), EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3), EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

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 https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
  • Enabling proxy certificate verification
  • Creating proxy certificates
  • Using proxy certs in applications
• NOTES
• SEE ALSO
• COPYRIGHT

NAME

proxy-certificates - Proxy certificates in OpenSSL

DESCRIPTION

Proxy certificates are defined in RFC 3820. They are used to extend rights to some other entity (a computer process, typically, or sometimes to the user itself). This allows the entity to perform operations on behalf of the owner of the EE (End Entity) certificate.

The requirements for a valid proxy certificate are:

• They are issued by an End Entity, either a normal EE certificate, or another proxy certificate.

• They must not have the subjectAltName or issuerAltName extensions.

• They must have the proxyCertInfo extension.

• They must have the subject of their issuer, with one commonName added.

Enabling proxy certificate verification

OpenSSL expects applications that want to use proxy certificates to be specially aware of them, and make that explicit. This is done by setting an X509 verification flag:

    X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);

or

    X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS);

See "NOTES" for a discussion on this requirement.

Creating proxy certificates

Creating proxy certificates can be done using the openssl-x509(1) command, with some extra extensions:

    [ v3_proxy ]
    # A proxy certificate MUST NEVER be a CA certificate.
    basicConstraints=CA:FALSE

    # Usual authority key ID
    authorityKeyIdentifier=keyid,issuer:always

    # The extension which marks this certificate as a proxy
    proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB

It's also possible to specify the proxy extension in a separate section:

    proxyCertInfo=critical,@proxy_ext

    [ proxy_ext ]
    language=id-ppl-anyLanguage
    pathlen=0
    policy=text:BC

The policy value has a specific syntax, syntag:string, where the syntag determines what will be done with the string. The following syntags are recognised:

text

indicates that the string is a byte sequence, without any encoding:

    policy=text:räksmörgås

hex

indicates the string is encoded hexadecimal encoded binary data, with colons between each byte (every second hex digit):

    policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73

file

indicates that the text of the policy should be taken from a file. The string is then a filename. This is useful for policies that are large (more than a few lines, e.g. XML documents).

NOTE: The proxy policy value is what determines the rights granted to the process during the proxy certificate. It's up to the application to interpret and combine these policies.

With a proxy extension, creating a proxy certificate is a matter of two commands:

    openssl req -new -config proxy.cnf \
        -out proxy.req -keyout proxy.key \
        -subj "/DC=org/DC=openssl/DC=users/CN=proxy 1"

    openssl x509 -req -CAcreateserial -in proxy.req -out proxy.crt \
        -CA user.crt -CAkey user.key -days 7 \
        -extfile proxy.cnf -extensions v3_proxy1

You can also create a proxy certificate using another proxy certificate as issuer (note: using a different configuration section for the proxy extensions):

    openssl req -new -config proxy.cnf \
        -out proxy2.req -keyout proxy2.key \
        -subj "/DC=org/DC=openssl/DC=users/CN=proxy 1/CN=proxy 2"

    openssl x509 -req -CAcreateserial -in proxy2.req -out proxy2.crt \
        -CA proxy.crt -CAkey proxy.key -days 7 \
        -extfile proxy.cnf -extensions v3_proxy2

Using proxy certs in applications

To interpret proxy policies, the application would normally start with some default rights (perhaps none at all), then compute the resulting rights by checking the rights against the chain of proxy certificates, user certificate and CA certificates.

The complicated part is figuring out how to pass data between your application and the certificate validation procedure.

The following ingredients are needed for such processing:

• a callback function that will be called for every certificate being validated. The callback is called several times for each certificate, so you must be careful to do the proxy policy interpretation at the right time. You also need to fill in the defaults when the EE certificate is checked.

• a data structure that is shared between your application code and the callback.

• a wrapper function that sets it all up.

• an ex_data index function that creates an index into the generic ex_data store that is attached to an X509 validation context.

The following skeleton code can be used as a starting point:

    #include <string.h>
    #include <netdb.h>
    #include <openssl/x509.h>
    #include <openssl/x509v3.h>

    #define total_rights 25

    /*
     * In this example, I will use a view of granted rights as a bit
     * array, one bit for each possible right.
     */
    typedef struct your_rights {
        unsigned char rights[(total_rights + 7) / 8];
    } YOUR_RIGHTS;

    /*
     * The following procedure will create an index for the ex_data
     * store in the X509 validation context the first time it's
     * called.  Subsequent calls will return the same index.
     */
    static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
    {
        static volatile int idx = -1;

        if (idx < 0) {
            X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
            if (idx < 0) {
                idx = X509_STORE_CTX_get_ex_new_index(0,
                                                      "for verify callback",
                                                      NULL,NULL,NULL);
            }
            X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
        }
        return idx;
    }

    /* Callback to be given to the X509 validation procedure.  */
    static int verify_callback(int ok, X509_STORE_CTX *ctx)
    {
        if (ok == 1) {
            /*
             * It's REALLY important you keep the proxy policy check
             * within this section.  It's important to know that when
             * ok is 1, the certificates are checked from top to
             * bottom.  You get the CA root first, followed by the
             * possible chain of intermediate CAs, followed by the EE
             * certificate, followed by the possible proxy
             * certificates. 
             */
            X509 *xs = X509_STORE_CTX_get_current_cert(ctx);

            if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
                YOUR_RIGHTS *rights =
                    (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
                        get_proxy_auth_ex_data_idx(ctx));
                PROXY_CERT_INFO_EXTENSION *pci =
                    X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);

                switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
                case NID_Independent:
                    /*
                     * Do whatever you need to grant explicit rights
                     * to this particular proxy certificate, usually
                     * by pulling them from some database.  If there
                     * are none to be found, clear all rights (making
                     * this and any subsequent proxy certificate void
                     * of any rights). 
                     */
                    memset(rights->rights, 0, sizeof(rights->rights));
                    break;
                case NID_id_ppl_inheritAll:
                    /*
                     * This is basically a NOP, we simply let the
                     * current rights stand as they are.
                     */
                    break;
                default:
                    /*
                     * This is usually the most complex section of
                     * code.  You really do whatever you want as long
                     * as you follow RFC 3820.  In the example we use
                     * here, the simplest thing to do is to build
                     * another, temporary bit array and fill it with
                     * the rights granted by the current proxy
                     * certificate, then use it as a mask on the
                     * accumulated rights bit array, and voilà, you
                     * now have a new accumulated rights bit array.
                     */
                    {
                        int i;
                        YOUR_RIGHTS tmp_rights;
                        memset(tmp_rights.rights, 0,
                               sizeof(tmp_rights.rights));

                        /*
                         * process_rights() is supposed to be a
                         * procedure that takes a string and its
                         * length, interprets it and sets the bits
                         * in the YOUR_RIGHTS pointed at by the
                         * third argument.
                         */
                        process_rights((char *) pci->proxyPolicy->policy->data,
                                       pci->proxyPolicy->policy->length,
                                       &tmp_rights);

                        for(i = 0; i < total_rights / 8; i++)
                            rights->rights[i] &= tmp_rights.rights[i];
                    }
                    break;
                }
                PROXY_CERT_INFO_EXTENSION_free(pci);
            } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
                /* We have an EE certificate, let's use it to set default! */
                YOUR_RIGHTS *rights =
                    (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
                        get_proxy_auth_ex_data_idx(ctx));

                /*
                 * The following procedure finds out what rights the
                 * owner of the current certificate has, and sets them
                 * in the YOUR_RIGHTS structure pointed at by the
                 * second argument.
                 */
                set_default_rights(xs, rights);
            }
        }
        return ok;
    }

    static int my_X509_verify_cert(X509_STORE_CTX *ctx,
                                   YOUR_RIGHTS *needed_rights)
    {
        int ok;
        int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
            X509_STORE_CTX_get_verify_cb(ctx);
        YOUR_RIGHTS rights;

        X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
        X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx),
                                   &rights);
        X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
        ok = X509_verify_cert(ctx);

        if (ok == 1) {
            ok = check_needed_rights(rights, needed_rights);
        }

        X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);

        return ok;
    }

If you use SSL or TLS, you can easily set up a callback to have the certificates checked properly, using the code above:

    SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert,
                                     &needed_rights);

NOTES

To this date, it seems that proxy certificates have only been used in environments that are aware of them, and no one seems to have investigated how they can be used or misused outside of such an environment.

For that reason, OpenSSL requires that applications aware of proxy certificates must also make that explicit.

subjectAltName and issuerAltName are forbidden in proxy certificates, and this is enforced in OpenSSL. The subject must be the same as the issuer, with one commonName added on.

SEE ALSO

X509_STORE_CTX_set_flags(3), X509_STORE_CTX_set_verify_cb(3), X509_VERIFY_PARAM_set_flags(3), SSL_CTX_set_cert_verify_callback(3), openssl-req(1), openssl-x509(1), RFC 3820

COPYRIGHT

Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

• NAME
• DESCRIPTION
  • The general case
  • PKCS#12
  • OSSL_STORE
• RECOMMENDATIONS
  • Creating new objects
  • Opening existing objects
• SEE ALSO
• COPYRIGHT

NAME

passphrase-encoding - How diverse parts of OpenSSL treat pass phrases character encoding

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.

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.

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:

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.

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).

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 DIAERESIS) 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.

OSSL_STORE

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.

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.

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 OPENSSL_WIN32_UTF8 will have anything entered on [Windows] console prompt converted to UTF-8 (command line and separately prompted pass phrases alike).

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:

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.

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.

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, ï, 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)

SEE ALSO

evp(7), ossl_store(7), EVP_BytesToKey(3), EVP_DecryptInit(3), PEM_do_header(3), PKCS12_parse(3), PKCS12_newpass(3), d2i_PKCS8PrivateKey_bio(3)

COPYRIGHT

Copyright 2018-2020 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 https://www.openssl.org/source/license.html.

• NAME
• SYNOPSIS
• DESCRIPTION
• SEE ALSO
• HISTORY
• COPYRIGHT

NAME

ct - Certificate Transparency

SYNOPSIS

 #include <openssl/ct.h>

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_enable_ct(3) or SSL_enable_ct(3).

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.

SEE ALSO

d2i_SCT_LIST(3), CTLOG_STORE_new(3), CTLOG_STORE_get0_log_by_id(3), SCT_new(3), SCT_print(3), SCT_validate(3), SCT_validate(3), CT_POLICY_EVAL_CTX_new(3), SSL_CTX_set_ct_validation_callback(3)

HISTORY

The ct library was added in OpenSSL 1.1.0.

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 https://www.openssl.org/source/license.html.