crypto

title: crypto(7)

summary: OpenSSL cryptographic library

text:
# crypto(7)

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


ct

package: openssl

title: ct(7)

summary: Certificate Transparency

text:
# ct(7)

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


title: des_modes(7)

text:
# des_modes(7)

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


evp

title: evp(7)

summary: high\-level cryptographic functions

text:
# evp(7)

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


title: ossl_store(7)

summary: Store retrieval functions

text:
# ossl_store(7)

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


title: ossl_store-file(7)

summary: The store 'file' scheme loader

text:
# ossl_store-file(7)

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


passphrase-encoding

title: passphrase-encoding(7)

text:
# passphrase-encoding(7)

## 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. "naieve" 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. "naieve" 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 naieve (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, "ie", which is 0xC3 0xAF when encoded in UTF-8, would become 0xC3 0x83 0xC2 0xAF when re-encoded in the naieve 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>.


proxy-certificates

title: proxy-certificates(7)

summary: Proxy certificates in OpenSSL

text:
# proxy-certificates(7)

## 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:raeksmoergaas

```

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 voila, 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 <https://tools.ietf.org/html/rfc3820>

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


scrypt

title: scrypt(7)

summary: EVP_PKEY scrypt KDF support

text:
# scrypt(7)

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


ssl

title: ssl(7)

summary: OpenSSL SSL/TLS library

text:
# ssl(7)

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


title: x509(7)

summary: X.509 certificate handling

text:
# x509(7)

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