From 8257c6e8a076c9973b3c13e1c5be3a7f4e4247c4 Mon Sep 17 00:00:00 2001 From: openssl-machine Date: Mon, 4 Nov 2024 09:24:48 +0000 Subject: [PATCH] deploy openssl/openssl@1ee906143c0b0ebb6bcbeb87277833a665e79836 to master --- master/man1/openssl-pkeyutl/index.html | 4 ++-- master/search/search_index.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/master/man1/openssl-pkeyutl/index.html b/master/man1/openssl-pkeyutl/index.html index 00df9eaa5..c587c457e 100644 --- a/master/man1/openssl-pkeyutl/index.html +++ b/master/man1/openssl-pkeyutl/index.html @@ -9,7 +9,7 @@ container.insertAdjacentElement("afterEnd", script) } -
Skip to content

openssl-pkeyutl

NAME

openssl-pkeyutl - public key algorithm command

SYNOPSIS

openssl pkeyutl [-help] [-in file] [-rawin] [-digest algorithm] [-out file] [-secret file] [-sigfile file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-peerkey file] [-peerform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-encap] [-decap] [-kdf algorithm] [-kdflen length] [-kemop operation] [-pkeyopt opt:value] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile]

DESCRIPTION

This command can be used to perform low-level public key operations using any supported algorithm.

OPTIONS

  • -help

    Print out a usage message.

  • -in filename

    This specifies the input filename to read data from or standard input if this option is not specified.

  • -rawin

    This indicates that the input data is raw data, which is not hashed by any message digest algorithm. The user can specify a digest algorithm by using the -digest option. This option can only be used with -sign and -verify and must be used with the Ed25519 and Ed448 algorithms.

  • -digest algorithm

    This specifies the digest algorithm which is used to hash the input data before signing or verifying it with the input key. This option could be omitted if the signature algorithm does not require one (for instance, EdDSA). If this option is omitted but the signature algorithm requires one, a default value will be used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the default digest algorithm. For SM2, it will be SM3. If this option is present, then the -rawin option must be also specified.

  • -out filename

    Specifies the output filename to write to or standard output by default.

  • -secret filename

    Specifies the output filename to write the secret to on -encap.

  • -sigfile file

    Signature file, required for -verify operations only

  • -inkey filename|uri

    The input key, by default it should be a private key.

  • -keyform DER|PEM|P12|ENGINE

    The key format; unspecified by default. See openssl-format-options(1) for details.

  • -passin arg

    The input key password source. For more information about the format of arg see openssl-passphrase-options(1).

  • -peerkey file

    The peer key file, used by key derivation (agreement) operations.

  • -peerform DER|PEM|P12|ENGINE

    The peer key format; unspecified by default. See openssl-format-options(1) for details.

  • -pubin

    By default a private key is read from the key input. With this option a public key is read instead. If the input contains no public key but a private key, its public part is used.

  • -certin

    The input is a certificate containing a public key.

  • -rev

    Reverse the order of the input buffer. This is useful for some libraries (such as CryptoAPI) which represent the buffer in little endian format.

  • -sign

    Sign the input data (which must be a hash) and output the signed result. This requires a private key.

  • -verify

    Verify the input data (which must be a hash) against the signature file and indicate if the verification succeeded or failed.

  • -verifyrecover

    Verify the input data (which must be a hash) and output the recovered data.

  • -encrypt

    Encrypt the input data using a public key.

  • -decrypt

    Decrypt the input data using a private key.

  • -derive

    Derive a shared secret using the peer key.

  • -encap

    Encapsulate a generated secret using a private key. The encapsulated result (binary data) is written to standard output by default, or else to the file specified with -out. The -secret option must also be provided to specify the output file for the secret value generated in the encapsulation process.

  • -decap

    Decapsulate the secret using a private key. The result (binary data) is written to standard output by default, or else to the file specified with -out.

  • -kemop operation

    This option is used for -encap/-decap commands and specifies the KEM operation specific for the key algorithm when there is no default KEM operation. If the algorithm has the default KEM operation, this option can be omitted.

    See EVP_PKEY_CTX_set_kem_op(3) and algorithm-specific KEM documentation e.g. EVP_KEM-RSA(7), EVP_KEM-EC(7), EVP_KEM-X25519(7), and EVP_KEM-X448(7).

  • -kdf algorithm

    Use key derivation function algorithm. The supported algorithms are at present TLS1-PRF and HKDF. Note: additional parameters and the KDF output length will normally have to be set for this to work. See EVP_PKEY_CTX_set_hkdf_md(3) and EVP_PKEY_CTX_set_tls1_prf_md(3) for the supported string parameters of each algorithm.

  • -kdflen length

    Set the output length for KDF.

  • -pkeyopt opt:value

    Public key options specified as opt:value. See NOTES below for more details.

  • -pkeyopt_passin opt[:passarg]

    Allows reading a public key option opt from stdin or a password source. If only opt is specified, the user will be prompted to enter a password on stdin. Alternatively, passarg can be specified which can be any value supported by openssl-passphrase-options(1).

  • -hexdump

    hex dump the output data.

  • -asn1parse

    Parse the ASN.1 output data, this is useful when combined with the -verifyrecover option when an ASN1 structure is signed.

  • -engine id

    See "Engine Options" in openssl(1). This option is deprecated.

  • -engine_impl

    When used with the -engine option, it specifies to also use engine id for crypto operations.

  • -rand files, -writerand file

    See "Random State Options" in openssl(1) for details.

  • -provider name

  • -provider-path path

  • -propquery propq

    See "Provider Options" in openssl(1), provider(7), and property(7).

  • -config configfile

    See "Configuration Option" in openssl(1).

NOTES

The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below.

Unless otherwise mentioned all algorithms support the digest:alg option which specifies the digest in use for sign, verify and verifyrecover operations. The value alg should represent a digest name as used in the EVP_get_digestbyname() function for example sha1. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the lengths of data passed in and for creating the structures that make up the signature (e.g. DigestInfo in RSASSA PKCS#1 v1.5 signatures).

This command does not hash the input data (except where -rawin is used) but rather it will use the data directly as input to the signature algorithm. Depending on the key type, signature type, and mode of padding, the maximum acceptable lengths of input data differ. The signed data can't be longer than the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer than the field size, otherwise it will be silently truncated to the field size. In any event the input size must not be larger than the largest supported digest size.

In other words, if the value of digest is sha1 the input should be the 20 bytes long binary encoding of the SHA-1 hash function output.

RSA ALGORITHM

The RSA algorithm generally supports the encrypt, decrypt, sign, verify and verifyrecover operations. However, some padding modes support only a subset of these operations. The following additional pkeyopt values are supported:

  • rsa_padding_mode:mode

    This sets the RSA padding mode. Acceptable values for mode are pkcs1 for PKCS#1 padding, none for no padding, oaep for OAEP mode, x931 for X9.31 mode and pss for PSS.

    In PKCS#1 padding, if the message digest is not set, then the supplied data is signed or verified directly instead of using a DigestInfo structure. If a digest is set, then the DigestInfo structure is used and its length must correspond to the digest type.

    Note, for pkcs1 padding, as a protection against the Bleichenbacher attack, the decryption will not fail in case of padding check failures. Use none and manual inspection of the decrypted message to verify if the decrypted value has correct PKCS#1 v1.5 padding.

    For oaep mode only encryption and decryption is supported.

    For x931 if the digest type is set it is used to format the block data otherwise the first byte is used to specify the X9.31 digest ID. Sign, verify and verifyrecover are can be performed in this mode.

    For pss mode only sign and verify are supported and the digest type must be specified.

  • rsa_pss_saltlen:len

    For pss mode only this option specifies the salt length. Three special values are supported: digest sets the salt length to the digest length, max sets the salt length to the maximum permissible value. When verifying auto causes the salt length to be automatically determined based on the PSS block structure.

  • rsa_mgf1_md:digest

    For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not explicitly set in PSS mode then the signing digest is used.

  • rsa_oaep_md:digest

    Sets the digest used for the OAEP hash function. If not explicitly set then SHA1 is used.

  • rsa_pkcs1_implicit_rejection:flag

    Disables (when set to 0) or enables (when set to 1) the use of implicit rejection with PKCS#1 v1.5 decryption. When enabled (the default), as a protection against Bleichenbacher attack, the library will generate a deterministic random plaintext that it will return to the caller in case of padding check failure. When disabled, it's the callers' responsibility to handle the returned errors in a side-channel free manner.

RSA-PSS ALGORITHM

The RSA-PSS algorithm is a restricted version of the RSA algorithm which only supports the sign and verify operations with PSS padding. The following additional -pkeyopt values are supported:

  • rsa_padding_mode:mode, rsa_pss_saltlen:len, rsa_mgf1_md:digest

    These have the same meaning as the RSA algorithm with some additional restrictions. The padding mode can only be set to pss which is the default value.

    If the key has parameter restrictions then the digest, MGF1 digest and salt length are set to the values specified in the parameters. The digest and MG cannot be changed and the salt length cannot be set to a value less than the minimum restriction.

DSA ALGORITHM

The DSA algorithm supports signing and verification operations only. Currently there are no additional -pkeyopt options other than digest. The SHA1 digest is assumed by default.

DH ALGORITHM

The DH algorithm only supports the derivation operation and no additional -pkeyopt options.

EC ALGORITHM

The EC algorithm supports sign, verify and derive operations. The sign and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for the -pkeyopt digest option.

X25519 AND X448 ALGORITHMS

The X25519 and X448 algorithms support key derivation only. Currently there are no additional options.

ED25519 AND ED448 ALGORITHMS

These algorithms only support signing and verifying. OpenSSL only implements the "pure" variants of these algorithms so raw data can be passed directly to them without hashing them first. The option -rawin must be used with these algorithms with no -digest specified. Additionally OpenSSL only supports "oneshot" operation with these algorithms. This means that the entire file to be signed/verified must be read into memory before processing it. Signing or Verifying very large files should be avoided. Additionally the size of the file must be known for this to work. If the size of the file cannot be determined (for example if the input is stdin) then the sign or verify operation will fail.

SM2

The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For the sign and verify operations, SM2 requires an Distinguishing ID string to be passed in. The following -pkeyopt value is supported:

  • distid:string

    This sets the ID string used in SM2 sign or verify operations. While verifying an SM2 signature, the ID string must be the same one used when signing the data. Otherwise the verification will fail.

  • hexdistid:hex_string

    This sets the ID string used in SM2 sign or verify operations. While verifying an SM2 signature, the ID string must be the same one used when signing the data. Otherwise the verification will fail. The ID string provided with this option should be a valid hexadecimal value.

EXAMPLES

Sign some data using a private key:

openssl pkeyutl -sign -in file -inkey key.pem -out sig
+
openssl-pkeyutl
NAME
openssl-pkeyutl - public key algorithm command
SYNOPSIS
openssl pkeyutl [-help] [-in file] [-rawin] [-digest algorithm] [-out file] [-secret file] [-sigfile file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-peerkey file] [-peerform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-encap] [-decap] [-kdf algorithm] [-kdflen length] [-kemop operation] [-pkeyopt opt:value] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile]
DESCRIPTION
This command can be used to perform low-level public key operations using any supported algorithm.
OPTIONS
  • -help
    Print out a usage message.
  • -in filename
    This specifies the input filename to read data from or standard input if this option is not specified.
  • -rawin
    This indicates that signature input data is raw data, which for most signature algorithms (but not EdDSA) needs to be hashed by some message digest algorithm. This option can only be used with -sign and -verify and is implied by the Ed25519 and Ed448 algorithms. Except with EdDSA, the user can specify a digest algorithm by using the -digest option.
    The -digest option implies -rawin.
  • -digest algorithm
    This option can only be used with -sign and -verify. It specifies the digest algorithm which is used to hash the input data before signing or verifying it with the input key. This option could be omitted if the signature algorithm does not require one (for instance, EdDSA). If this option is omitted but the signature algorithm requires one, a default value will be used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the default digest algorithm. For SM2, it will be SM3. At this time, HashEdDSA (the ph or "prehash" variant of EdDSA) is not supported, so the -digest option cannot be used with EdDSA).
  • -out filename
    Specifies the output filename to write to or standard output by default.
  • -secret filename
    Specifies the output filename to write the secret to on -encap.
  • -sigfile file
    Signature file, required for -verify operations only
  • -inkey filename|uri
    The input key, by default it should be a private key.
  • -keyform DER|PEM|P12|ENGINE
    The key format; unspecified by default. See openssl-format-options(1) for details.
  • -passin arg
    The input key password source. For more information about the format of arg see openssl-passphrase-options(1).
  • -peerkey file
    The peer key file, used by key derivation (agreement) operations.
  • -peerform DER|PEM|P12|ENGINE
    The peer key format; unspecified by default. See openssl-format-options(1) for details.
  • -pubin
    By default a private key is read from the key input. With this option a public key is read instead. If the input contains no public key but a private key, its public part is used.
  • -certin
    The input is a certificate containing a public key.
  • -rev
    Reverse the order of the input buffer. This is useful for some libraries (such as CryptoAPI) which represent the buffer in little endian format. This cannot be used in conjunction with -rawin.
  • -sign
    Sign the input data (which must be a hash) and output the signed result. This requires a private key.
  • -verify
    Verify the input data (which must be a hash) against the signature file and indicate if the verification succeeded or failed.
  • -verifyrecover
    Verify the input data (which must be a hash) and output the recovered data.
  • -encrypt
    Encrypt the input data using a public key.
  • -decrypt
    Decrypt the input data using a private key.
  • -derive
    Derive a shared secret using the peer key.
  • -encap
    Encapsulate a generated secret using a private key. The encapsulated result (binary data) is written to standard output by default, or else to the file specified with -out. The -secret option must also be provided to specify the output file for the secret value generated in the encapsulation process.
  • -decap
    Decapsulate the secret using a private key. The result (binary data) is written to standard output by default, or else to the file specified with -out.
  • -kemop operation
    This option is used for -encap/-decap commands and specifies the KEM operation specific for the key algorithm when there is no default KEM operation. If the algorithm has the default KEM operation, this option can be omitted.
    See EVP_PKEY_CTX_set_kem_op(3) and algorithm-specific KEM documentation e.g. EVP_KEM-RSA(7), EVP_KEM-EC(7), EVP_KEM-X25519(7), and EVP_KEM-X448(7).
  • -kdf algorithm
    Use key derivation function algorithm. The supported algorithms are at present TLS1-PRF and HKDF. Note: additional parameters and the KDF output length will normally have to be set for this to work. See EVP_PKEY_CTX_set_hkdf_md(3) and EVP_PKEY_CTX_set_tls1_prf_md(3) for the supported string parameters of each algorithm.
  • -kdflen length
    Set the output length for KDF.
  • -pkeyopt opt:value
    Public key options specified as opt:value. See NOTES below for more details.
  • -pkeyopt_passin opt[:passarg]
    Allows reading a public key option opt from stdin or a password source. If only opt is specified, the user will be prompted to enter a password on stdin. Alternatively, passarg can be specified which can be any value supported by openssl-passphrase-options(1).
  • -hexdump
    hex dump the output data.
  • -asn1parse
    Parse the ASN.1 output data, this is useful when combined with the -verifyrecover option when an ASN1 structure is signed.
  • -engine id
    See "Engine Options" in openssl(1). This option is deprecated.
  • -engine_impl
    When used with the -engine option, it specifies to also use engine id for crypto operations.
  • -rand files, -writerand file
    See "Random State Options" in openssl(1) for details.
  • -provider name
  • -provider-path path
  • -propquery propq
    See "Provider Options" in openssl(1), provider(7), and property(7).
  • -config configfile
    See "Configuration Option" in openssl(1).
NOTES
The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below.
Unless otherwise mentioned all algorithms support the digest:alg option which specifies the digest in use for sign, verify and verifyrecover operations. The value alg should represent a digest name as used in the EVP_get_digestbyname() function for example sha1. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the lengths of data passed in and for creating the structures that make up the signature (e.g. DigestInfo in RSASSA PKCS#1 v1.5 signatures).
This command does not hash the input data (except where -rawin is used) but rather it will use the data directly as input to the signature algorithm. Depending on the key type, signature type, and mode of padding, the maximum acceptable lengths of input data differ. The signed data can't be longer than the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer than the field size, otherwise it will be silently truncated to the field size. In any event the input size must not be larger than the largest supported digest size.
In other words, if the value of digest is sha1 the input should be the 20 bytes long binary encoding of the SHA-1 hash function output.
RSA ALGORITHM
The RSA algorithm generally supports the encrypt, decrypt, sign, verify and verifyrecover operations. However, some padding modes support only a subset of these operations. The following additional pkeyopt values are supported:
  • rsa_padding_mode:mode
    This sets the RSA padding mode. Acceptable values for mode are pkcs1 for PKCS#1 padding, none for no padding, oaep for OAEP mode, x931 for X9.31 mode and pss for PSS.
    In PKCS#1 padding, if the message digest is not set, then the supplied data is signed or verified directly instead of using a DigestInfo structure. If a digest is set, then the DigestInfo structure is used and its length must correspond to the digest type.
    Note, for pkcs1 padding, as a protection against the Bleichenbacher attack, the decryption will not fail in case of padding check failures. Use none and manual inspection of the decrypted message to verify if the decrypted value has correct PKCS#1 v1.5 padding.
    For oaep mode only encryption and decryption is supported.
    For x931 if the digest type is set it is used to format the block data otherwise the first byte is used to specify the X9.31 digest ID. Sign, verify and verifyrecover are can be performed in this mode.
    For pss mode only sign and verify are supported and the digest type must be specified.
  • rsa_pss_saltlen:len
    For pss mode only this option specifies the salt length. Three special values are supported: digest sets the salt length to the digest length, max sets the salt length to the maximum permissible value. When verifying auto causes the salt length to be automatically determined based on the PSS block structure.
  • rsa_mgf1_md:digest
    For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not explicitly set in PSS mode then the signing digest is used.
  • rsa_oaep_md:digest
    Sets the digest used for the OAEP hash function. If not explicitly set then SHA1 is used.
  • rsa_pkcs1_implicit_rejection:flag
    Disables (when set to 0) or enables (when set to 1) the use of implicit rejection with PKCS#1 v1.5 decryption. When enabled (the default), as a protection against Bleichenbacher attack, the library will generate a deterministic random plaintext that it will return to the caller in case of padding check failure. When disabled, it's the callers' responsibility to handle the returned errors in a side-channel free manner.
RSA-PSS ALGORITHM
The RSA-PSS algorithm is a restricted version of the RSA algorithm which only supports the sign and verify operations with PSS padding. The following additional -pkeyopt values are supported:
  • rsa_padding_mode:mode, rsa_pss_saltlen:len, rsa_mgf1_md:digest
    These have the same meaning as the RSA algorithm with some additional restrictions. The padding mode can only be set to pss which is the default value.
    If the key has parameter restrictions then the digest, MGF1 digest and salt length are set to the values specified in the parameters. The digest and MG cannot be changed and the salt length cannot be set to a value less than the minimum restriction.
DSA ALGORITHM
The DSA algorithm supports signing and verification operations only. Currently there are no additional -pkeyopt options other than digest. The SHA1 digest is assumed by default.
DH ALGORITHM
The DH algorithm only supports the derivation operation and no additional -pkeyopt options.
EC ALGORITHM
The EC algorithm supports sign, verify and derive operations. The sign and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for the -pkeyopt digest option.
X25519 AND X448 ALGORITHMS
The X25519 and X448 algorithms support key derivation only. Currently there are no additional options.
ED25519 AND ED448 ALGORITHMS
These algorithms only support signing and verifying. OpenSSL only implements the "pure" variants of these algorithms so raw data can be passed directly to them without hashing them first. The option -rawin must be used with these algorithms with no -digest specified. Additionally OpenSSL only supports "oneshot" operation with these algorithms. This means that the entire file to be signed/verified must be read into memory before processing it. Signing or Verifying very large files should be avoided. Additionally the size of the file must be known for this to work. If the size of the file cannot be determined (for example if the input is stdin) then the sign or verify operation will fail.
SM2
The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For the sign and verify operations, SM2 requires an Distinguishing ID string to be passed in. The following -pkeyopt value is supported:
  • distid:string
    This sets the ID string used in SM2 sign or verify operations. While verifying an SM2 signature, the ID string must be the same one used when signing the data. Otherwise the verification will fail.
  • hexdistid:hex_string
    This sets the ID string used in SM2 sign or verify operations. While verifying an SM2 signature, the ID string must be the same one used when signing the data. Otherwise the verification will fail. The ID string provided with this option should be a valid hexadecimal value.
EXAMPLES
Sign some data using a private key:
openssl pkeyutl -sign -in file -inkey key.pem -out sig
 
Recover the signed data (e.g. if an RSA key is used):
openssl pkeyutl -verifyrecover -in sig -inkey key.pem
 
Verify the signature (e.g. a DSA key):
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
 
Sign data using a message digest value (this is currently only valid for RSA):
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
@@ -26,4 +26,4 @@
    -rawin -digest sm3 -pkeyopt distid:someid
 
Decrypt some data using a private key with OAEP padding using SHA256:
openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \
    -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
-
SEE ALSO
openssl(1), openssl-genpkey(1), openssl-pkey(1), openssl-rsautl(1)openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1), openssl-kdf(1)EVP_PKEY_CTX_set_hkdf_md(3), EVP_PKEY_CTX_set_tls1_prf_md(3),
HISTORY
The -engine option was deprecated in OpenSSL 3.0.
Copyright 2006-2024 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.

\ No newline at end of file
+

SEE ALSO

openssl(1), openssl-genpkey(1), openssl-pkey(1), openssl-rsautl(1)openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1), openssl-kdf(1)EVP_PKEY_CTX_set_hkdf_md(3), EVP_PKEY_CTX_set_tls1_prf_md(3),

HISTORY

Since OpenSSL 3.5, the -digest option implies -rawin, and these two options are no longer required when signing or verifying with an Ed25519 or Ed448 key.

The -engine option was deprecated in OpenSSL 3.0.

Copyright 2006-2024 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.

\ No newline at end of file diff --git a/master/search/search_index.json b/master/search/search_index.json index dae41423b..cdc8cdbf5 100644 --- a/master/search/search_index.json +++ b/master/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"man1/CA.pl/","title":"CA.pl","text":""},{"location":"man1/CA.pl/#name","title":"NAME","text":"

CA.pl - friendlier interface for OpenSSL certificate programs

"},{"location":"man1/CA.pl/#synopsis","title":"SYNOPSIS","text":"

CA.pl -? | -h | -help

CA.pl -newcert | -newreq | -newreq-nodes | -xsign | -sign | -signCA | -signcert | -crl | -newca [-extra-cmd parameter]

CA.pl -pkcs12 [certname]

CA.pl -verify certfile ...

CA.pl -revoke certfile [reason]

"},{"location":"man1/CA.pl/#description","title":"DESCRIPTION","text":"

The CA.pl script is a perl script that supplies the relevant command line arguments to the openssl(1) command for some common certificate operations. It is intended to simplify the process of certificate creation and management by the use of some simple options.

The script is intended as a simple front end for the openssl(1) program for use by a beginner. Its behaviour isn't always what is wanted. For more control over the behaviour of the certificate commands call the openssl(1) command directly.

Most of the filenames mentioned below can be modified by editing the CA.pl script.

Under some environments it may not be possible to run the CA.pl script directly (for example Win32) and the default configuration file location may be wrong. In this case the command:

perl -S CA.pl\n

can be used and the OPENSSL_CONF environment variable can be set to point to the correct path of the configuration file.

"},{"location":"man1/CA.pl/#options","title":"OPTIONS","text":""},{"location":"man1/CA.pl/#examples","title":"EXAMPLES","text":"

Create a CA hierarchy:

CA.pl -newca\n

Complete certificate creation example: create a CA, create a request, sign the request and finally create a PKCS#12 file containing it.

CA.pl -newca\nCA.pl -newreq\nCA.pl -sign\nCA.pl -pkcs12 \"My Test Certificate\"\n
"},{"location":"man1/CA.pl/#environment","title":"ENVIRONMENT","text":"

The environment variable OPENSSL may be used to specify the name of the OpenSSL program. It can be a full pathname, or a relative one.

The environment variable OPENSSL_CONFIG may be used to specify a configuration option and value to the req and ca commands invoked by this script. It's value should be the option and pathname, as in -config /path/to/conf-file.

"},{"location":"man1/CA.pl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-x509(1), openssl-ca(1), openssl-req(1), openssl-pkcs12(1), config(5)

"},{"location":"man1/CA.pl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-asn1parse/","title":"openssl-asn1parse","text":""},{"location":"man1/openssl-asn1parse/#name","title":"NAME","text":"

openssl-asn1parse - ASN.1 parsing command

"},{"location":"man1/openssl-asn1parse/#synopsis","title":"SYNOPSIS","text":"

openssl asn1parse [-help] [-inform DER|PEM|B64] [-in filename] [-out filename] [-noout] [-offset number] [-length number] [-i] [-oid filename] [-dump] [-dlimit num] [-strparse offset] [-genstr string] [-genconf file] [-strictpem] [-item name]

"},{"location":"man1/openssl-asn1parse/#description","title":"DESCRIPTION","text":"

This command is a diagnostic utility that can parse ASN.1 structures. It can also be used to extract data from ASN.1 formatted data.

"},{"location":"man1/openssl-asn1parse/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-asn1parse/#output","title":"Output","text":"

The output will typically contain lines like this:

0:d=0  hl=4 l= 681 cons: SEQUENCE\n

.....

229:d=3  hl=3 l= 141 prim: BIT STRING\n373:d=2  hl=3 l= 162 cons: cont [ 3 ]\n376:d=3  hl=3 l= 159 cons: SEQUENCE\n379:d=4  hl=2 l=  29 cons: SEQUENCE\n381:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Subject Key Identifier\n386:d=5  hl=2 l=  22 prim: OCTET STRING\n410:d=4  hl=2 l= 112 cons: SEQUENCE\n412:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Authority Key Identifier\n417:d=5  hl=2 l= 105 prim: OCTET STRING\n524:d=4  hl=2 l=  12 cons: SEQUENCE\n

.....

This example is part of a self-signed certificate. Each line starts with the offset in decimal. d=XX specifies the current depth. The depth is increased within the scope of any SET or SEQUENCE. hl=XX gives the header length (tag and length octets) of the current type. l=XX gives the length of the contents octets.

The -i option can be used to make the output more readable.

Some knowledge of the ASN.1 structure is needed to interpret the output.

In this example the BIT STRING at offset 229 is the certificate public key. The contents octets of this will contain the public key information. This can be examined using the option -strparse 229 to yield:

  0:d=0  hl=3 l= 137 cons: SEQUENCE\n  3:d=1  hl=3 l= 129 prim: INTEGER           :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897\n135:d=1  hl=2 l=   3 prim: INTEGER           :010001\n
"},{"location":"man1/openssl-asn1parse/#notes","title":"NOTES","text":"

If an OID is not part of OpenSSL's internal table it will be represented in numerical form (for example 1.2.3.4). The file passed to the -oid option allows additional OIDs to be included. Each line consists of three columns, the first column is the OID in numerical format and should be followed by white space. The second column is the \"short name\" which is a single word followed by whitespace. The final column is the rest of the line and is the \"long name\". Example:

1.2.3.4 shortName A long name

For any OID with an associated short and long name, this command will display the long name.

"},{"location":"man1/openssl-asn1parse/#examples","title":"EXAMPLES","text":"

Parse a file:

openssl asn1parse -in file.pem\n

Parse a DER file:

openssl asn1parse -inform DER -in file.der\n

Generate a simple UTF8String:

openssl asn1parse -genstr 'UTF8:Hello World'\n

Generate and write out a UTF8String, don't print parsed output:

openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der\n

Generate using a config file:

openssl asn1parse -genconf asn1.cnf -noout -out asn1.der\n

Example config file:

asn1=SEQUENCE:seq_sect\n\n[seq_sect]\n\nfield1=BOOL:TRUE\nfield2=EXP:0, UTF8:some random string\n
"},{"location":"man1/openssl-asn1parse/#bugs","title":"BUGS","text":"

There should be options to change the format of output lines. The output of some ASN.1 types is not well handled (if at all).

"},{"location":"man1/openssl-asn1parse/#see-also","title":"SEE ALSO","text":"

openssl(1), ASN1_generate_nconf(3)

"},{"location":"man1/openssl-asn1parse/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-ca/","title":"openssl-ca","text":""},{"location":"man1/openssl-ca/#name","title":"NAME","text":"

openssl-ca - sample minimal CA application

"},{"location":"man1/openssl-ca/#synopsis","title":"SYNOPSIS","text":"

openssl ca [-help] [-verbose] [-quiet] [-config filename] [-name section] [-section section] [-gencrl] [-revoke file] [-valid file] [-status serial] [-updatedb] [-crl_reason reason] [-crl_hold instruction] [-crl_compromise time] [-crl_CA_compromise time] [-crl_lastupdate date] [-crl_nextupdate date] [-crldays days] [-crlhours hours] [-crlsec seconds] [-crlexts section] [-startdate date] [-not_before date] [-enddate date] [-not_after date] [-days arg] [-md arg] [-policy arg] [-keyfile filename|uri] [-keyform DER|PEM|P12|ENGINE] [-key arg] [-passin arg] [-cert file] [-certform DER|PEM|P12] [-selfsign] [-in file] [-inform DER|<PEM>] [-out file] [-notext] [-dateopt] [-outdir dir] [-infiles] [-spkac file] [-ss_cert file] [-preserveDN] [-noemailDN] [-batch] [-msie_hack] [-extensions section] [-extfile section] [-subj arg] [-utf8] [-sigopt nm:v] [-vfyopt nm:v] [-create_serial] [-rand_serial] [-multivalue-rdn] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [certreq...]

"},{"location":"man1/openssl-ca/#description","title":"DESCRIPTION","text":"

This command emulates a CA application. See the WARNINGS especially when considering to use it productively.

It generates certificates bearing X.509 version 3. Unless specified otherwise, key identifier extensions are included as described in x509v3_config(5).

It can be used to sign certificate requests (CSRs) in a variety of forms and generate certificate revocation lists (CRLs). It also maintains a text database of issued certificates and their status. When signing certificates, a single request can be specified with the -in option, or multiple requests can be processed by specifying a set of certreq files after all options.

Note that there are also very lean ways of generating certificates: the req and x509 commands can be used for directly creating certificates. See openssl-req(1) and openssl-x509(1) for details.

The descriptions of the ca command options are divided into each purpose.

"},{"location":"man1/openssl-ca/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ca/#crl-options","title":"CRL OPTIONS","text":""},{"location":"man1/openssl-ca/#configuration-file-options","title":"CONFIGURATION FILE OPTIONS","text":"

The section of the configuration file containing options for this command is found as follows: If the -name command line option is used, then it names the section to be used. Otherwise the section to be used must be named in the default_ca option of the ca section of the configuration file (or in the default section of the configuration file). Besides default_ca, the following options are read directly from the ca section: RANDFILE preserve msie_hack With the exception of RANDFILE, this is probably a bug and may change in future releases.

Many of the configuration file options are identical to command line options. Where the option is present in the configuration file and the command line the command line value is used. Where an option is described as mandatory then it must be present in the configuration file or the command line equivalent (if any) used.

"},{"location":"man1/openssl-ca/#policy-format","title":"POLICY FORMAT","text":"

The policy section consists of a set of variables corresponding to certificate DN fields. If the value is \"match\" then the field value must match the same field in the CA certificate. If the value is \"supplied\" then it must be present. If the value is \"optional\" then it may be present. Any fields not mentioned in the policy section are silently deleted, unless the -preserveDN option is set but this can be regarded more of a quirk than intended behaviour.

"},{"location":"man1/openssl-ca/#spkac-format","title":"SPKAC FORMAT","text":"

The input to the -spkac command line option is a Netscape signed public key and challenge. This will usually come from the KEYGEN tag in an HTML form to create a new private key. It is however possible to create SPKACs using openssl-spkac(1).

The file should contain the variable SPKAC set to the value of the SPKAC and also the required DN components as name value pairs. If you need to include the same component twice then it can be preceded by a number and a '.'.

When processing SPKAC format, the output is DER if the -out flag is used, but PEM format if sending to stdout or the -outdir flag is used.

"},{"location":"man1/openssl-ca/#examples","title":"EXAMPLES","text":"

Note: these examples assume that the directory structure this command assumes is already set up and the relevant files already exist. This usually involves creating a CA certificate and private key with openssl-req(1), a serial number file and an empty index file and placing them in the relevant directories.

To use the sample configuration file below the directories demoCA, demoCA/private and demoCA/newcerts would be created. The CA certificate would be copied to demoCA/cacert.pem and its private key to demoCA/private/cakey.pem. A file demoCA/serial would be created containing for example \"01\" and the empty index file demoCA/index.txt.

Sign a certificate request:

openssl ca -in req.pem -out newcert.pem\n

Sign an SM2 certificate request:

openssl ca -in sm2.csr -out sm2.crt -md sm3 \\\n        -sigopt \"distid:1234567812345678\" \\\n        -vfyopt \"distid:1234567812345678\"\n

Sign a certificate request, using CA extensions:

openssl ca -in req.pem -extensions v3_ca -out newcert.pem\n

Generate a CRL

openssl ca -gencrl -out crl.pem\n

Sign several requests:

openssl ca -infiles req1.pem req2.pem req3.pem\n

Certify a Netscape SPKAC:

openssl ca -spkac spkac.txt\n

A sample SPKAC file (the SPKAC line has been truncated for clarity):

SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5\nCN=Steve Test\nemailAddress=steve@openssl.org\n0.OU=OpenSSL Group\n1.OU=Another Group\n

A sample configuration file with the relevant sections for this command:

[ ca ]\ndefault_ca      = CA_default         #   # The default ca section\n\n[ CA_default ]\n\ndir            = ./demoCA           #   # top dir\ndatabase       = $dir/index.txt     #   # index file.\nnew_certs_dir  = $dir/newcerts      #   # new certs dir\n\ncertificate    = $dir/cacert.pem    #   # The CA cert\nserial         = $dir/serial        #   # serial no file\n#rand_serial    = yes               #   # for random serial#'s\nprivate_key    = $dir/private/cakey.pem## CA private key\n\ndefault_days   = 365                #   # how long to certify for\ndefault_crl_days= 30                #   # how long before next CRL\ndefault_md     = md5                #   # md to use\n\npolicy         = policy_any         #   # default policy\nemail_in_dn    = no                 #   # Don't add the email into cert DN\n\nname_opt       = ca_default         #   # Subject name display option\ncert_opt       = ca_default         #   # Certificate display option\ncopy_extensions = none              #   # Don't copy extensions from request\n\n[ policy_any ]\ncountryName            = supplied\nstateOrProvinceName    = optional\norganizationName       = optional\norganizationalUnitName = optional\ncommonName             = supplied\nemailAddress           = optional\n
"},{"location":"man1/openssl-ca/#files","title":"FILES","text":"

Note: the location of all files can change either by compile time options, configuration file entries, environment variables or command line options. The values below reflect the default values.

/usr/local/ssl/lib/openssl.cnf - master configuration file\n./demoCA                       - main CA directory\n./demoCA/cacert.pem            - CA certificate\n./demoCA/private/cakey.pem     - CA private key\n./demoCA/serial                - CA serial number file\n./demoCA/serial.old            - CA serial number backup file\n./demoCA/index.txt             - CA text database file\n./demoCA/index.txt.old         - CA text database backup file\n./demoCA/certs                 - certificate output file\n
"},{"location":"man1/openssl-ca/#restrictions","title":"RESTRICTIONS","text":"

The text database index file is a critical part of the process and if corrupted it can be difficult to fix. It is theoretically possible to rebuild the index file from all the issued certificates and a current CRL: however there is no option to do this.

V2 CRL features like delta CRLs are not currently supported.

Although several requests can be input and handled at once it is only possible to include one SPKAC or self-signed certificate.

"},{"location":"man1/openssl-ca/#bugs","title":"BUGS","text":"

This command is quirky and at times downright unfriendly.

The use of an in-memory text database can cause problems when large numbers of certificates are present because, as the name implies the database has to be kept in memory.

This command really needs rewriting or the required functionality exposed at either a command or interface level so that a more user-friendly replacement could handle things properly. The script CA.pl helps a little but not very much.

Any fields in a request that are not present in a policy are silently deleted. This does not happen if the -preserveDN option is used. To enforce the absence of the EMAIL field within the DN, as suggested by RFCs, regardless the contents of the request' subject the -noemailDN option can be used. The behaviour should be more friendly and configurable.

Canceling some commands by refusing to certify a certificate can create an empty file.

"},{"location":"man1/openssl-ca/#warnings","title":"WARNINGS","text":"

This command was originally meant as an example of how to do things in a CA. Its code does not have production quality. It was not supposed to be used as a full blown CA itself, nevertheless some people are using it for this purpose at least internally. When doing so, specific care should be taken to properly secure the private key(s) used for signing certificates. It is advisable to keep them in a secure HW storage such as a smart card or HSM and access them via a suitable engine or crypto provider.

This command is effectively a single user command: no locking is done on the various files and attempts to run more than one openssl ca command on the same database can have unpredictable results.

The copy_extensions option should be used with caution. If care is not taken then it can be a security risk. For example if a certificate request contains a basicConstraints extension with CA:TRUE and the copy_extensions value is set to copyall and the user does not spot this when the certificate is displayed then this will hand the requester a valid CA certificate. This situation can be avoided by setting copy_extensions to copy and including basicConstraints with CA:FALSE in the configuration file. Then if the request contains a basicConstraints extension it will be ignored.

It is advisable to also include values for other extensions such as keyUsage to prevent a request supplying its own values.

Additional restrictions can be placed on the CA certificate itself. For example if the CA certificate has:

basicConstraints = CA:TRUE, pathlen:0\n

then even if a certificate is issued with CA:TRUE it will not be valid.

"},{"location":"man1/openssl-ca/#history","title":"HISTORY","text":"

Since OpenSSL 1.1.1, the program follows RFC5280. Specifically, certificate validity period (specified by any of -startdate, -enddate and -days) and CRL last/next update time (specified by any of -crl_lastupdate, -crl_nextupdate, -crldays, -crlhours and -crlsec) will be encoded as UTCTime if the dates are earlier than year 2049 (included), and as GeneralizedTime if the dates are in year 2050 or later.

OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved seeding mechanism. The new seeding mechanism makes it unnecessary to define a RANDFILE for saving and restoring randomness. This option is retained mainly for compatibility reasons.

The -section option was added in OpenSSL 3.0.0.

The -multivalue-rdn option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0.

Since OpenSSL 3.2, generated certificates bear X.509 version 3, and key identifier extensions are included by default.

"},{"location":"man1/openssl-ca/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-req(1), openssl-spkac(1), openssl-x509(1), CA.pl(1), config(5), x509v3_config(5)

"},{"location":"man1/openssl-ca/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-ciphers/","title":"openssl-ciphers","text":""},{"location":"man1/openssl-ciphers/#name","title":"NAME","text":"

openssl-ciphers - SSL cipher display and cipher list command

"},{"location":"man1/openssl-ciphers/#synopsis","title":"SYNOPSIS","text":"

openssl ciphers [-help] [-s] [-v] [-V] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-s] [-psk] [-srp] [-stdname] [-convert name] [-ciphersuites val] [-provider name] [-provider-path path] [-propquery propq] [cipherlist]

"},{"location":"man1/openssl-ciphers/#description","title":"DESCRIPTION","text":"

This command converts textual OpenSSL cipher lists into ordered SSL cipher preference lists. It can be used to determine the appropriate cipherlist.

"},{"location":"man1/openssl-ciphers/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ciphers/#cipher-list-format","title":"CIPHER LIST FORMAT","text":"

The cipher list consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used.

The cipher string may reference a cipher using its standard name from the IANA TLS Cipher Suites Registry (https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).

The actual cipher string can take several different forms.

It can consist of a single cipher suite such as RC4-SHA.

It can represent a list of cipher suites containing a certain algorithm, or cipher suites of a certain type. For example SHA1 represents all ciphers suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3 algorithms.

Lists of cipher suites can be combined in a single cipher string using the + character. This is used as a logical and operation. For example SHA1+DES represents all cipher suites containing the SHA1 and the DES algorithms.

Each cipher string can be optionally preceded by the characters !, - or +.

If ! is used then the ciphers are permanently deleted from the list. The ciphers deleted can never reappear in the list even if they are explicitly stated.

If - is used then the ciphers are deleted from the list, but some or all of the ciphers can be added again by later options.

If + is used then the ciphers are moved to the end of the list. This option doesn't add any new ciphers it just moves matching existing ones.

If none of these characters is present then the string is just interpreted as a list of ciphers to be appended to the current preference list. If the list includes any ciphers already present they will be ignored: that is they will not moved to the end of the list.

The cipher string @STRENGTH can be used at any point to sort the current cipher list in order of encryption algorithm key length.

The cipher string @SECLEVEL=n can be used at any point to set the security level to n, which should be a number between zero and five, inclusive. See SSL_CTX_set_security_level(3) for a description of what each level means.

The cipher list can be prefixed with the DEFAULT keyword, which enables the default cipher list as defined below. Unlike cipher strings, this prefix may not be combined with other strings using + character. For example, DEFAULT+DES is not valid.

The content of the default list is determined at compile time and normally corresponds to ALL:!COMPLEMENTOFDEFAULT:!eNULL.

"},{"location":"man1/openssl-ciphers/#cipher-strings","title":"CIPHER STRINGS","text":"

The following is a list of all permitted cipher strings and their meanings.

"},{"location":"man1/openssl-ciphers/#cipher-suite-names","title":"CIPHER SUITE NAMES","text":"

The following lists give the standard SSL or TLS cipher suites names from the relevant specification and their OpenSSL equivalents. You can use either standard names or OpenSSL names in cipher lists, or a mix of both.

It should be noted, that several cipher suite names do not include the authentication used, e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.

"},{"location":"man1/openssl-ciphers/#ssl-v30-cipher-suites","title":"SSL v3.0 cipher suites","text":"
SSL_RSA_WITH_NULL_MD5                   NULL-MD5\nSSL_RSA_WITH_NULL_SHA                   NULL-SHA\nSSL_RSA_WITH_RC4_128_MD5                RC4-MD5\nSSL_RSA_WITH_RC4_128_SHA                RC4-SHA\nSSL_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA\nSSL_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA\n\nSSL_DH_DSS_WITH_3DES_EDE_CBC_SHA        DH-DSS-DES-CBC3-SHA\nSSL_DH_RSA_WITH_3DES_EDE_CBC_SHA        DH-RSA-DES-CBC3-SHA\nSSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA       DHE-DSS-DES-CBC3-SHA\nSSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA       DHE-RSA-DES-CBC3-SHA\n\nSSL_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5\nSSL_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA\n\nSSL_FORTEZZA_KEA_WITH_NULL_SHA          Not implemented.\nSSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA  Not implemented.\nSSL_FORTEZZA_KEA_WITH_RC4_128_SHA       Not implemented.\n
"},{"location":"man1/openssl-ciphers/#tls-v10-cipher-suites","title":"TLS v1.0 cipher suites","text":"
TLS_RSA_WITH_NULL_MD5                   NULL-MD5\nTLS_RSA_WITH_NULL_SHA                   NULL-SHA\nTLS_RSA_WITH_RC4_128_MD5                RC4-MD5\nTLS_RSA_WITH_RC4_128_SHA                RC4-SHA\nTLS_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA\nTLS_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA\n\nTLS_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.\nTLS_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.\nTLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA       DHE-DSS-DES-CBC3-SHA\nTLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA       DHE-RSA-DES-CBC3-SHA\n\nTLS_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5\nTLS_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA\n
"},{"location":"man1/openssl-ciphers/#aes-cipher-suites-from-rfc3268-extending-tls-v10","title":"AES cipher suites from RFC3268, extending TLS v1.0","text":"
TLS_RSA_WITH_AES_128_CBC_SHA            AES128-SHA\nTLS_RSA_WITH_AES_256_CBC_SHA            AES256-SHA\n\nTLS_DH_DSS_WITH_AES_128_CBC_SHA         DH-DSS-AES128-SHA\nTLS_DH_DSS_WITH_AES_256_CBC_SHA         DH-DSS-AES256-SHA\nTLS_DH_RSA_WITH_AES_128_CBC_SHA         DH-RSA-AES128-SHA\nTLS_DH_RSA_WITH_AES_256_CBC_SHA         DH-RSA-AES256-SHA\n\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA        DHE-DSS-AES128-SHA\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA        DHE-DSS-AES256-SHA\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA        DHE-RSA-AES128-SHA\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA        DHE-RSA-AES256-SHA\n\nTLS_DH_anon_WITH_AES_128_CBC_SHA        ADH-AES128-SHA\nTLS_DH_anon_WITH_AES_256_CBC_SHA        ADH-AES256-SHA\n
"},{"location":"man1/openssl-ciphers/#camellia-cipher-suites-from-rfc4132-extending-tls-v10","title":"Camellia cipher suites from RFC4132, extending TLS v1.0","text":"
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA      CAMELLIA128-SHA\nTLS_RSA_WITH_CAMELLIA_256_CBC_SHA      CAMELLIA256-SHA\n\nTLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA   DH-DSS-CAMELLIA128-SHA\nTLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA   DH-DSS-CAMELLIA256-SHA\nTLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA   DH-RSA-CAMELLIA128-SHA\nTLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA   DH-RSA-CAMELLIA256-SHA\n\nTLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA  DHE-DSS-CAMELLIA128-SHA\nTLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA  DHE-DSS-CAMELLIA256-SHA\nTLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA  DHE-RSA-CAMELLIA128-SHA\nTLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA  DHE-RSA-CAMELLIA256-SHA\n\nTLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA  ADH-CAMELLIA128-SHA\nTLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA  ADH-CAMELLIA256-SHA\n
"},{"location":"man1/openssl-ciphers/#seed-cipher-suites-from-rfc4162-extending-tls-v10","title":"SEED cipher suites from RFC4162, extending TLS v1.0","text":"
TLS_RSA_WITH_SEED_CBC_SHA              SEED-SHA\n\nTLS_DH_DSS_WITH_SEED_CBC_SHA           DH-DSS-SEED-SHA\nTLS_DH_RSA_WITH_SEED_CBC_SHA           DH-RSA-SEED-SHA\n\nTLS_DHE_DSS_WITH_SEED_CBC_SHA          DHE-DSS-SEED-SHA\nTLS_DHE_RSA_WITH_SEED_CBC_SHA          DHE-RSA-SEED-SHA\n\nTLS_DH_anon_WITH_SEED_CBC_SHA          ADH-SEED-SHA\n
"},{"location":"man1/openssl-ciphers/#gost-cipher-suites-from-draft-chudov-cryptopro-cptls-extending-tls-v10","title":"GOST cipher suites from draft-chudov-cryptopro-cptls, extending TLS v1.0","text":"

Note: these ciphers require an engine which including GOST cryptographic algorithms, such as the gost engine, which isn't part of the OpenSSL distribution.

TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89\nTLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89\nTLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94\nTLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94\n
"},{"location":"man1/openssl-ciphers/#gost-cipher-suites-extending-tls-v12","title":"GOST cipher suites, extending TLS v1.2","text":"

Note: these ciphers require an engine which including GOST cryptographic algorithms, such as the gost engine, which isn't part of the OpenSSL distribution.

TLS_GOSTR341112_256_WITH_28147_CNT_IMIT GOST2012-GOST8912-GOST8912\nTLS_GOSTR341112_256_WITH_NULL_GOSTR3411 GOST2012-NULL-GOST12\n

Note: GOST2012-GOST8912-GOST8912 is an alias for two ciphers ID old LEGACY-GOST2012-GOST8912-GOST8912 and new IANA-GOST2012-GOST8912-GOST8912

"},{"location":"man1/openssl-ciphers/#additional-export-1024-and-other-cipher-suites","title":"Additional Export 1024 and other cipher suites","text":"

Note: these ciphers can also be used in SSL v3.

TLS_DHE_DSS_WITH_RC4_128_SHA            DHE-DSS-RC4-SHA\n
"},{"location":"man1/openssl-ciphers/#elliptic-curve-cipher-suites","title":"Elliptic curve cipher suites","text":"
TLS_ECDHE_RSA_WITH_NULL_SHA             ECDHE-RSA-NULL-SHA\nTLS_ECDHE_RSA_WITH_RC4_128_SHA          ECDHE-RSA-RC4-SHA\nTLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA     ECDHE-RSA-DES-CBC3-SHA\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA      ECDHE-RSA-AES128-SHA\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA      ECDHE-RSA-AES256-SHA\n\nTLS_ECDHE_ECDSA_WITH_NULL_SHA           ECDHE-ECDSA-NULL-SHA\nTLS_ECDHE_ECDSA_WITH_RC4_128_SHA        ECDHE-ECDSA-RC4-SHA\nTLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA   ECDHE-ECDSA-DES-CBC3-SHA\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA    ECDHE-ECDSA-AES128-SHA\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA    ECDHE-ECDSA-AES256-SHA\n\nTLS_ECDH_anon_WITH_NULL_SHA             AECDH-NULL-SHA\nTLS_ECDH_anon_WITH_RC4_128_SHA          AECDH-RC4-SHA\nTLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA     AECDH-DES-CBC3-SHA\nTLS_ECDH_anon_WITH_AES_128_CBC_SHA      AECDH-AES128-SHA\nTLS_ECDH_anon_WITH_AES_256_CBC_SHA      AECDH-AES256-SHA\n
"},{"location":"man1/openssl-ciphers/#tls-v12-cipher-suites","title":"TLS v1.2 cipher suites","text":"
TLS_RSA_WITH_NULL_SHA256                  NULL-SHA256\n\nTLS_RSA_WITH_AES_128_CBC_SHA256           AES128-SHA256\nTLS_RSA_WITH_AES_256_CBC_SHA256           AES256-SHA256\nTLS_RSA_WITH_AES_128_GCM_SHA256           AES128-GCM-SHA256\nTLS_RSA_WITH_AES_256_GCM_SHA384           AES256-GCM-SHA384\n\nTLS_DH_RSA_WITH_AES_128_CBC_SHA256        DH-RSA-AES128-SHA256\nTLS_DH_RSA_WITH_AES_256_CBC_SHA256        DH-RSA-AES256-SHA256\nTLS_DH_RSA_WITH_AES_128_GCM_SHA256        DH-RSA-AES128-GCM-SHA256\nTLS_DH_RSA_WITH_AES_256_GCM_SHA384        DH-RSA-AES256-GCM-SHA384\n\nTLS_DH_DSS_WITH_AES_128_CBC_SHA256        DH-DSS-AES128-SHA256\nTLS_DH_DSS_WITH_AES_256_CBC_SHA256        DH-DSS-AES256-SHA256\nTLS_DH_DSS_WITH_AES_128_GCM_SHA256        DH-DSS-AES128-GCM-SHA256\nTLS_DH_DSS_WITH_AES_256_GCM_SHA384        DH-DSS-AES256-GCM-SHA384\n\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA256       DHE-RSA-AES128-SHA256\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA256       DHE-RSA-AES256-SHA256\nTLS_DHE_RSA_WITH_AES_128_GCM_SHA256       DHE-RSA-AES128-GCM-SHA256\nTLS_DHE_RSA_WITH_AES_256_GCM_SHA384       DHE-RSA-AES256-GCM-SHA384\n\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA256       DHE-DSS-AES128-SHA256\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA256       DHE-DSS-AES256-SHA256\nTLS_DHE_DSS_WITH_AES_128_GCM_SHA256       DHE-DSS-AES128-GCM-SHA256\nTLS_DHE_DSS_WITH_AES_256_GCM_SHA384       DHE-DSS-AES256-GCM-SHA384\n\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256     ECDHE-RSA-AES128-SHA256\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384     ECDHE-RSA-AES256-SHA384\nTLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256     ECDHE-RSA-AES128-GCM-SHA256\nTLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384     ECDHE-RSA-AES256-GCM-SHA384\n\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256   ECDHE-ECDSA-AES128-SHA256\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384   ECDHE-ECDSA-AES256-SHA384\nTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256   ECDHE-ECDSA-AES128-GCM-SHA256\nTLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384   ECDHE-ECDSA-AES256-GCM-SHA384\n\nTLS_DH_anon_WITH_AES_128_CBC_SHA256       ADH-AES128-SHA256\nTLS_DH_anon_WITH_AES_256_CBC_SHA256       ADH-AES256-SHA256\nTLS_DH_anon_WITH_AES_128_GCM_SHA256       ADH-AES128-GCM-SHA256\nTLS_DH_anon_WITH_AES_256_GCM_SHA384       ADH-AES256-GCM-SHA384\n\nRSA_WITH_AES_128_CCM                      AES128-CCM\nRSA_WITH_AES_256_CCM                      AES256-CCM\nDHE_RSA_WITH_AES_128_CCM                  DHE-RSA-AES128-CCM\nDHE_RSA_WITH_AES_256_CCM                  DHE-RSA-AES256-CCM\nRSA_WITH_AES_128_CCM_8                    AES128-CCM8\nRSA_WITH_AES_256_CCM_8                    AES256-CCM8\nDHE_RSA_WITH_AES_128_CCM_8                DHE-RSA-AES128-CCM8\nDHE_RSA_WITH_AES_256_CCM_8                DHE-RSA-AES256-CCM8\nECDHE_ECDSA_WITH_AES_128_CCM              ECDHE-ECDSA-AES128-CCM\nECDHE_ECDSA_WITH_AES_256_CCM              ECDHE-ECDSA-AES256-CCM\nECDHE_ECDSA_WITH_AES_128_CCM_8            ECDHE-ECDSA-AES128-CCM8\nECDHE_ECDSA_WITH_AES_256_CCM_8            ECDHE-ECDSA-AES256-CCM8\n
"},{"location":"man1/openssl-ciphers/#aria-cipher-suites-from-rfc6209-extending-tls-v12","title":"ARIA cipher suites from RFC6209, extending TLS v1.2","text":"

Note: the CBC modes mentioned in this RFC are not supported.

TLS_RSA_WITH_ARIA_128_GCM_SHA256          ARIA128-GCM-SHA256\nTLS_RSA_WITH_ARIA_256_GCM_SHA384          ARIA256-GCM-SHA384\nTLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256      DHE-RSA-ARIA128-GCM-SHA256\nTLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384      DHE-RSA-ARIA256-GCM-SHA384\nTLS_DHE_DSS_WITH_ARIA_128_GCM_SHA256      DHE-DSS-ARIA128-GCM-SHA256\nTLS_DHE_DSS_WITH_ARIA_256_GCM_SHA384      DHE-DSS-ARIA256-GCM-SHA384\nTLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256  ECDHE-ECDSA-ARIA128-GCM-SHA256\nTLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384  ECDHE-ECDSA-ARIA256-GCM-SHA384\nTLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256    ECDHE-ARIA128-GCM-SHA256\nTLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384    ECDHE-ARIA256-GCM-SHA384\nTLS_PSK_WITH_ARIA_128_GCM_SHA256          PSK-ARIA128-GCM-SHA256\nTLS_PSK_WITH_ARIA_256_GCM_SHA384          PSK-ARIA256-GCM-SHA384\nTLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256      DHE-PSK-ARIA128-GCM-SHA256\nTLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384      DHE-PSK-ARIA256-GCM-SHA384\nTLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256      RSA-PSK-ARIA128-GCM-SHA256\nTLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384      RSA-PSK-ARIA256-GCM-SHA384\n
"},{"location":"man1/openssl-ciphers/#camellia-hmac-based-cipher-suites-from-rfc6367-extending-tls-v12","title":"Camellia HMAC-Based cipher suites from RFC6367, extending TLS v1.2","text":"
TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256\nTLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384\nTLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256   ECDHE-RSA-CAMELLIA128-SHA256\nTLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384   ECDHE-RSA-CAMELLIA256-SHA384\n
"},{"location":"man1/openssl-ciphers/#pre-shared-keying-psk-cipher-suites","title":"Pre-shared keying (PSK) cipher suites","text":"
PSK_WITH_NULL_SHA                         PSK-NULL-SHA\nDHE_PSK_WITH_NULL_SHA                     DHE-PSK-NULL-SHA\nRSA_PSK_WITH_NULL_SHA                     RSA-PSK-NULL-SHA\n\nPSK_WITH_RC4_128_SHA                      PSK-RC4-SHA\nPSK_WITH_3DES_EDE_CBC_SHA                 PSK-3DES-EDE-CBC-SHA\nPSK_WITH_AES_128_CBC_SHA                  PSK-AES128-CBC-SHA\nPSK_WITH_AES_256_CBC_SHA                  PSK-AES256-CBC-SHA\n\nDHE_PSK_WITH_RC4_128_SHA                  DHE-PSK-RC4-SHA\nDHE_PSK_WITH_3DES_EDE_CBC_SHA             DHE-PSK-3DES-EDE-CBC-SHA\nDHE_PSK_WITH_AES_128_CBC_SHA              DHE-PSK-AES128-CBC-SHA\nDHE_PSK_WITH_AES_256_CBC_SHA              DHE-PSK-AES256-CBC-SHA\n\nRSA_PSK_WITH_RC4_128_SHA                  RSA-PSK-RC4-SHA\nRSA_PSK_WITH_3DES_EDE_CBC_SHA             RSA-PSK-3DES-EDE-CBC-SHA\nRSA_PSK_WITH_AES_128_CBC_SHA              RSA-PSK-AES128-CBC-SHA\nRSA_PSK_WITH_AES_256_CBC_SHA              RSA-PSK-AES256-CBC-SHA\n\nPSK_WITH_AES_128_GCM_SHA256               PSK-AES128-GCM-SHA256\nPSK_WITH_AES_256_GCM_SHA384               PSK-AES256-GCM-SHA384\nDHE_PSK_WITH_AES_128_GCM_SHA256           DHE-PSK-AES128-GCM-SHA256\nDHE_PSK_WITH_AES_256_GCM_SHA384           DHE-PSK-AES256-GCM-SHA384\nRSA_PSK_WITH_AES_128_GCM_SHA256           RSA-PSK-AES128-GCM-SHA256\nRSA_PSK_WITH_AES_256_GCM_SHA384           RSA-PSK-AES256-GCM-SHA384\n\nPSK_WITH_AES_128_CBC_SHA256               PSK-AES128-CBC-SHA256\nPSK_WITH_AES_256_CBC_SHA384               PSK-AES256-CBC-SHA384\nPSK_WITH_NULL_SHA256                      PSK-NULL-SHA256\nPSK_WITH_NULL_SHA384                      PSK-NULL-SHA384\nDHE_PSK_WITH_AES_128_CBC_SHA256           DHE-PSK-AES128-CBC-SHA256\nDHE_PSK_WITH_AES_256_CBC_SHA384           DHE-PSK-AES256-CBC-SHA384\nDHE_PSK_WITH_NULL_SHA256                  DHE-PSK-NULL-SHA256\nDHE_PSK_WITH_NULL_SHA384                  DHE-PSK-NULL-SHA384\nRSA_PSK_WITH_AES_128_CBC_SHA256           RSA-PSK-AES128-CBC-SHA256\nRSA_PSK_WITH_AES_256_CBC_SHA384           RSA-PSK-AES256-CBC-SHA384\nRSA_PSK_WITH_NULL_SHA256                  RSA-PSK-NULL-SHA256\nRSA_PSK_WITH_NULL_SHA384                  RSA-PSK-NULL-SHA384\nPSK_WITH_AES_128_GCM_SHA256               PSK-AES128-GCM-SHA256\nPSK_WITH_AES_256_GCM_SHA384               PSK-AES256-GCM-SHA384\n\nECDHE_PSK_WITH_RC4_128_SHA                ECDHE-PSK-RC4-SHA\nECDHE_PSK_WITH_3DES_EDE_CBC_SHA           ECDHE-PSK-3DES-EDE-CBC-SHA\nECDHE_PSK_WITH_AES_128_CBC_SHA            ECDHE-PSK-AES128-CBC-SHA\nECDHE_PSK_WITH_AES_256_CBC_SHA            ECDHE-PSK-AES256-CBC-SHA\nECDHE_PSK_WITH_AES_128_CBC_SHA256         ECDHE-PSK-AES128-CBC-SHA256\nECDHE_PSK_WITH_AES_256_CBC_SHA384         ECDHE-PSK-AES256-CBC-SHA384\nECDHE_PSK_WITH_NULL_SHA                   ECDHE-PSK-NULL-SHA\nECDHE_PSK_WITH_NULL_SHA256                ECDHE-PSK-NULL-SHA256\nECDHE_PSK_WITH_NULL_SHA384                ECDHE-PSK-NULL-SHA384\n\nPSK_WITH_CAMELLIA_128_CBC_SHA256          PSK-CAMELLIA128-SHA256\nPSK_WITH_CAMELLIA_256_CBC_SHA384          PSK-CAMELLIA256-SHA384\n\nDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256      DHE-PSK-CAMELLIA128-SHA256\nDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384      DHE-PSK-CAMELLIA256-SHA384\n\nRSA_PSK_WITH_CAMELLIA_128_CBC_SHA256      RSA-PSK-CAMELLIA128-SHA256\nRSA_PSK_WITH_CAMELLIA_256_CBC_SHA384      RSA-PSK-CAMELLIA256-SHA384\n\nECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256    ECDHE-PSK-CAMELLIA128-SHA256\nECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384    ECDHE-PSK-CAMELLIA256-SHA384\n\nPSK_WITH_AES_128_CCM                      PSK-AES128-CCM\nPSK_WITH_AES_256_CCM                      PSK-AES256-CCM\nDHE_PSK_WITH_AES_128_CCM                  DHE-PSK-AES128-CCM\nDHE_PSK_WITH_AES_256_CCM                  DHE-PSK-AES256-CCM\nPSK_WITH_AES_128_CCM_8                    PSK-AES128-CCM8\nPSK_WITH_AES_256_CCM_8                    PSK-AES256-CCM8\nDHE_PSK_WITH_AES_128_CCM_8                DHE-PSK-AES128-CCM8\nDHE_PSK_WITH_AES_256_CCM_8                DHE-PSK-AES256-CCM8\n
"},{"location":"man1/openssl-ciphers/#chacha20-poly1305-cipher-suites-extending-tls-v12","title":"ChaCha20-Poly1305 cipher suites, extending TLS v1.2","text":"
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256      ECDHE-RSA-CHACHA20-POLY1305\nTLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256    ECDHE-ECDSA-CHACHA20-POLY1305\nTLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256        DHE-RSA-CHACHA20-POLY1305\nTLS_PSK_WITH_CHACHA20_POLY1305_SHA256            PSK-CHACHA20-POLY1305\nTLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256      ECDHE-PSK-CHACHA20-POLY1305\nTLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256        DHE-PSK-CHACHA20-POLY1305\nTLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256        RSA-PSK-CHACHA20-POLY1305\n
"},{"location":"man1/openssl-ciphers/#tls-v13-cipher-suites","title":"TLS v1.3 cipher suites","text":"
TLS_AES_128_GCM_SHA256                     TLS_AES_128_GCM_SHA256\nTLS_AES_256_GCM_SHA384                     TLS_AES_256_GCM_SHA384\nTLS_CHACHA20_POLY1305_SHA256               TLS_CHACHA20_POLY1305_SHA256\nTLS_AES_128_CCM_SHA256                     TLS_AES_128_CCM_SHA256\nTLS_AES_128_CCM_8_SHA256                   TLS_AES_128_CCM_8_SHA256\n
"},{"location":"man1/openssl-ciphers/#tls-v13-integrity-only-cipher-suites-according-to-rfc-9150","title":"TLS v1.3 integrity-only cipher suites according to RFC 9150","text":"
TLS_SHA256_SHA256          TLS_SHA256_SHA256\nTLS_SHA384_SHA384          TLS_SHA384_SHA384\n

Note: these ciphers are purely HMAC based and do not provide any confidentiality and thus are disabled by default. These ciphers are only available at security level 0.

"},{"location":"man1/openssl-ciphers/#older-names-used-by-openssl","title":"Older names used by OpenSSL","text":"

The following names are accepted by older releases:

SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA    EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)\nSSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA    EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)\n
"},{"location":"man1/openssl-ciphers/#notes","title":"NOTES","text":"

Some compiled versions of OpenSSL may not include all the ciphers listed here because some ciphers were excluded at compile time.

"},{"location":"man1/openssl-ciphers/#examples","title":"EXAMPLES","text":"

Verbose listing of all OpenSSL ciphers including NULL ciphers:

openssl ciphers -v 'ALL:eNULL'\n

Include all ciphers except NULL and anonymous DH then sort by strength:

openssl ciphers -v 'ALL:!ADH:@STRENGTH'\n

Include all ciphers except ones with no encryption (eNULL) or no authentication (aNULL):

openssl ciphers -v 'ALL:!aNULL'\n

Include only 3DES ciphers and then place RSA ciphers last:

openssl ciphers -v '3DES:+RSA'\n

Include all RC4 ciphers but leave out those without authentication:

openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'\n

Include all ciphers with RSA authentication but leave out ciphers without encryption.

openssl ciphers -v 'RSA:!COMPLEMENTOFALL'\n

Set security level to 2 and display all ciphers consistent with level 2:

openssl ciphers -s -v 'ALL:@SECLEVEL=2'\n
"},{"location":"man1/openssl-ciphers/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-s_client(1), openssl-s_server(1), ssl(7)

"},{"location":"man1/openssl-ciphers/#history","title":"HISTORY","text":"

The -V option was added in OpenSSL 1.0.0.

The -stdname is only available if OpenSSL is built with tracing enabled (enable-ssl-trace argument to Configure) before OpenSSL 1.1.1.

The -convert option was added in OpenSSL 1.1.1.

Support for standard IANA names in cipher lists was added in OpenSSL 3.2.0.

The support for TLS v1.3 integrity-only cipher suites was added in OpenSSL 3.4.

"},{"location":"man1/openssl-ciphers/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-cmds/","title":"openssl-cmds","text":""},{"location":"man1/openssl-cmds/#name","title":"NAME","text":"

asn1parse, ca, ciphers, cmp, cms, crl, crl2pkcs7, dgst, dhparam, dsa, dsaparam, ec, ecparam, enc, engine, errstr, gendsa, genpkey, genrsa, info, kdf, mac, nseq, ocsp, passwd, pkcs12, pkcs7, pkcs8, pkey, pkeyparam, pkeyutl, prime, rand, rehash, req, rsa, rsautl, s_client, s_server, s_time, sess_id, smime, speed, spkac, srp, storeutl, ts, verify, version, x509 - OpenSSL application commands

"},{"location":"man1/openssl-cmds/#synopsis","title":"SYNOPSIS","text":"

openssl cmd -help | [-option | -option arg] ... [arg] ...

"},{"location":"man1/openssl-cmds/#description","title":"DESCRIPTION","text":"

Every cmd listed above is a (sub-)command of the openssl(1) application. It has its own detailed manual page at openssl-cmd(1). For example, to view the manual page for the openssl dgst command, type man openssl-dgst.

"},{"location":"man1/openssl-cmds/#options","title":"OPTIONS","text":"

Among others, every subcommand has a help option.

"},{"location":"man1/openssl-cmds/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-asn1parse(1), openssl-ca(1), openssl-ciphers(1), openssl-cmp(1), openssl-cms(1), openssl-crl(1), openssl-crl2pkcs7(1), openssl-dgst(1), openssl-dhparam(1), openssl-dsa(1), openssl-dsaparam(1), openssl-ec(1), openssl-ecparam(1), openssl-enc(1), openssl-engine(1), openssl-errstr(1), openssl-gendsa(1), openssl-genpkey(1), openssl-genrsa(1), openssl-info(1), openssl-kdf(1), openssl-mac(1), openssl-nseq(1), openssl-ocsp(1), openssl-passwd(1), openssl-pkcs12(1), openssl-pkcs7(1), openssl-pkcs8(1), openssl-pkey(1), openssl-pkeyparam(1), openssl-pkeyutl(1), openssl-prime(1), openssl-rand(1), openssl-rehash(1), openssl-req(1), openssl-rsa(1), openssl-rsautl(1), openssl-s_client(1), openssl-s_server(1), openssl-s_time(1), openssl-sess_id(1), openssl-smime(1), openssl-speed(1), openssl-spkac(1), openssl-srp(1), openssl-storeutl(1), openssl-ts(1), openssl-verify(1), openssl-version(1), openssl-x509(1),

"},{"location":"man1/openssl-cmds/#history","title":"HISTORY","text":"

Initially, the manual page entry for the openssl _cmd_ command used to be available at cmd(1). Later, the alias openssl-cmd(1) was introduced, which made it easier to group the openssl commands using the apropos(1) command or the shell's tab completion.

In order to reduce cluttering of the global manual page namespace, the manual page entries without the 'openssl-' prefix have been deprecated in OpenSSL 3.0 and will be removed in OpenSSL 4.0.

"},{"location":"man1/openssl-cmds/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-cmp/","title":"openssl-cmp","text":""},{"location":"man1/openssl-cmp/#name","title":"NAME","text":"

openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application

"},{"location":"man1/openssl-cmp/#synopsis","title":"SYNOPSIS","text":"

openssl cmp [-help] [-config filename] [-section names] [-verbosity level]

Generic message options:

[-cmd ir|cr|kur|p10cr|rr|genm] [-infotype name] [-profile name] [-geninfo values] [-template filename] [-keyspec filename]

Certificate enrollment options:

[-newkey filename|uri] [-newkeypass arg] [-subject name] [-days number] [-reqexts name] [-sans spec] [-san_nodefault] [-policies name] [-policy_oids names] [-policy_oids_critical] [-popo number] [-csr filename] [-out_trusted filenames|uris] [-implicit_confirm] [-disable_confirm] [-certout filename] [-chainout filename]

Certificate enrollment and revocation options:

[-oldcert filename|uri] [-issuer name] [-serial number] [-revreason number]

Message transfer options:

[-server [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-no_proxy addresses] [-recipient name] [-path remote_path] [-keep_alive value] [-msg_timeout seconds] [-total_timeout seconds]

Server authentication options:

[-trusted filenames|uris] [-untrusted filenames|uris] [-srvcert filename|uri] [-expect_sender name] [-ignore_keyusage] [-unprotected_errors] [-no_cache_extracerts] [-srvcertout filename] [-extracertsout filename] [-cacertsout filename] [-oldwithold filename] [-newwithnew filename] [-newwithold filename] [-oldwithnew filename] [-crlcert filename] [-oldcrl filename] [-crlout filename]

Client authentication and protection options:

[-ref value] [-secret arg] [-cert filename|uri] [-own_trusted filenames|uris] [-key filename|uri] [-keypass arg] [-digest name] [-mac name] [-extracerts filenames|uris] [-unprotected_requests]

Credentials format options:

[-certform PEM|DER] [-crlform PEM|DER] [-keyform PEM|DER|P12|ENGINE] [-otherpass arg] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

Random state options:

[-rand files] [-writerand file]

TLS connection options:

[-tls_used] [-tls_cert filename|uri] [-tls_key filename|uri] [-tls_keypass arg] [-tls_extra filenames|uris] [-tls_trusted filenames|uris] [-tls_host name]

Client-side debugging options:

[-batch] [-repeat number] [-reqin filenames] [-reqin_new_tid] [-reqout filenames] [-reqout_only filename] [-rspin filenames] [-rspout filenames] [-use_mock_srv]

Mock server options:

[-port number] [-max_msgs number] [-srv_ref value] [-srv_secret arg] [-srv_cert filename|uri] [-srv_key filename|uri] [-srv_keypass arg] [-srv_trusted filenames|uris] [-srv_untrusted filenames|uris] [-ref_cert filename|uri] [-rsp_cert filename|uri] [-rsp_crl filename|uri] [-rsp_extracerts filenames|uris] [-rsp_capubs filenames|uris] [-rsp_newwithnew filename|uri] [-rsp_newwithold filename|uri] [-rsp_oldwithnew filename|uri] [-poll_count number] [-check_after number] [-grant_implicitconf] [-pkistatus number] [-failure number] [-failurebits number] [-statusstring arg] [-send_error] [-send_unprotected] [-send_unprot_err] [-accept_unprotected] [-accept_unprot_err] [-accept_raverified]

Certificate verification options, for both CMP and TLS:

[-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]

"},{"location":"man1/openssl-cmp/#description","title":"DESCRIPTION","text":"

The cmp command is a client implementation for the Certificate Management Protocol (CMP) as defined in RFC4210. It can be used to request certificates from a CA server, update their certificates, request certificates to be revoked, and perform other types of CMP requests.

"},{"location":"man1/openssl-cmp/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-cmp/#generic-message-options","title":"Generic message options","text":""},{"location":"man1/openssl-cmp/#certificate-enrollment-options","title":"Certificate enrollment options","text":""},{"location":"man1/openssl-cmp/#certificate-enrollment-and-revocation-options","title":"Certificate enrollment and revocation options","text":""},{"location":"man1/openssl-cmp/#message-transfer-options","title":"Message transfer options","text":""},{"location":"man1/openssl-cmp/#server-authentication-options","title":"Server authentication options","text":""},{"location":"man1/openssl-cmp/#client-authentication-options","title":"Client authentication options","text":""},{"location":"man1/openssl-cmp/#credentials-format-options","title":"Credentials format options","text":""},{"location":"man1/openssl-cmp/#provider-options","title":"Provider options","text":""},{"location":"man1/openssl-cmp/#random-state-options","title":"Random state options","text":""},{"location":"man1/openssl-cmp/#tls-connection-options","title":"TLS connection options","text":""},{"location":"man1/openssl-cmp/#client-side-options-for-debugging-and-offline-scenarios","title":"Client-side options for debugging and offline scenarios","text":""},{"location":"man1/openssl-cmp/#mock-server-options","title":"Mock server options","text":""},{"location":"man1/openssl-cmp/#certificate-verification-options-for-both-cmp-and-tls","title":"Certificate verification options, for both CMP and TLS","text":""},{"location":"man1/openssl-cmp/#notes","title":"NOTES","text":"

When a client obtains, from a CMP server, CA certificates that it is going to trust, for instance via the caPubs field of a certificate response or using general messages with infoType caCerts or rootCaCert, authentication of the CMP server is particularly critical. So special care must be taken setting up server authentication using -trusted and related options for certificate-based authentication or -secret for MAC-based protection. If authentication is certificate-based, the -srvcertout option should be used to obtain the validated server certificate and perform an authorization check based on it.

When setting up CMP configurations and experimenting with enrollment options typically various errors occur until the configuration is correct and complete. When the CMP server reports an error the client will by default check the protection of the CMP response message. Yet some CMP services tend not to protect negative responses. In this case the client will reject them, and thus their contents are not shown although they usually contain hints that would be helpful for diagnostics. For assisting in such cases the CMP client offers a workaround via the -unprotected_errors option, which allows accepting such negative messages.

If OpenSSL was built with trace support enabled (e.g., ./config enable-trace) and the environment variable OPENSSL_TRACE includes HTTP, the requests and the response headers transferred via HTTP are printed.

"},{"location":"man1/openssl-cmp/#examples","title":"EXAMPLES","text":""},{"location":"man1/openssl-cmp/#simple-examples-using-the-default-openssl-configuration-file","title":"Simple examples using the default OpenSSL configuration file","text":"

This CMP client implementation comes with demonstrative CMP sections in the example configuration file openssl/apps/openssl.cnf, which can be used to interact conveniently with the Insta Demo CA.

In order to enroll an initial certificate from that CA it is sufficient to issue the following shell commands.

export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf\n\nopenssl genrsa -out insta.priv.pem\nopenssl cmp -section insta\n

This should produce the file insta.cert.pem containing a new certificate for the private key held in insta.priv.pem. It can be viewed using, e.g.,

openssl x509 -noout -text -in insta.cert.pem\n

In case the network setup requires using an HTTP proxy it may be given as usual via the environment variable http_proxy or via the -proxy option in the configuration file or the CMP command-line argument -proxy, for example

-proxy http://192.168.1.1:8080\n

In the Insta Demo CA scenario both clients and the server may use the pre-shared secret insta and the reference value 3078 to authenticate to each other.

Alternatively, CMP messages may be protected in signature-based manner, where the trust anchor in this case is insta.ca.crt and the client may use any certificate already obtained from that CA, as specified in the [signature] section of the example configuration. This can be used in combination with the [insta] section simply by

openssl cmp -section insta,signature\n

By default the CMP IR message type is used, yet CR works equally here. This may be specified directly at the command line:

openssl cmp -section insta -cmd cr\n

or by referencing in addition the [cr] section of the example configuration:

openssl cmp -section insta,cr\n

In order to update the enrolled certificate one may call

openssl cmp -section insta,kur\n

using MAC-based protection with PBM or

openssl cmp -section insta,kur,signature\n

using signature-based protection.

In a similar way any previously enrolled certificate may be revoked by

openssl cmp -section insta,rr -trusted insta.ca.crt\n

or

openssl cmp -section insta,rr,signature\n

Many more options can be given in the configuration file and/or on the command line. For instance, the -reqexts CLI option may refer to a section in the configuration file defining X.509 extensions to use in certificate requests, such as v3_req in openssl/apps/openssl.cnf:

openssl cmp -section insta,cr -reqexts v3_req\n
"},{"location":"man1/openssl-cmp/#certificate-enrollment","title":"Certificate enrollment","text":"

The following examples do not make use of a configuration file at first. They assume that a CMP server can be contacted on the local TCP port 80 and accepts requests under the alias /pkix/.

For enrolling its very first certificate the client generates a client key and sends an initial request message to the local CMP server using a pre-shared secret key for mutual authentication. In this example the client does not have the CA certificate yet, so we specify the name of the CA with the -recipient option and save any CA certificates that we may receive in the capubs.pem file.

In below command line usage examples the \\ at line ends is used just for formatting; each of the command invocations should be on a single line.

openssl genrsa -out cl_key.pem\nopenssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient \"/CN=CMPserver\" \\\n  -ref 1234 -secret pass:1234-5678 \\\n  -newkey cl_key.pem -subject \"/CN=MyName\" \\\n  -cacertsout capubs.pem -certout cl_cert.pem\n
"},{"location":"man1/openssl-cmp/#certificate-update","title":"Certificate update","text":"

Then, when the client certificate and its related key pair needs to be updated, the client can send a key update request taking the certs in capubs.pem as trusted for authenticating the server and using the previous cert and key for its own authentication. Then it can start using the new cert and key.

openssl genrsa -out cl_key_new.pem\nopenssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \\\n  -trusted capubs.pem \\\n  -cert cl_cert.pem -key cl_key.pem \\\n  -newkey cl_key_new.pem -certout cl_cert.pem\ncp cl_key_new.pem cl_key.pem\n

This command sequence can be repeated as often as needed.

"},{"location":"man1/openssl-cmp/#requesting-information-from-cmp-server","title":"Requesting information from CMP server","text":"

Requesting \"all relevant information\" with an empty General Message. This prints information about all received ITAV infoTypes to stdout.

openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient \"/CN=CMPserver\" \\\n  -ref 1234 -secret pass:1234-5678\n
"},{"location":"man1/openssl-cmp/#using-a-custom-configuration-file","title":"Using a custom configuration file","text":"

For CMP client invocations, in particular for certificate enrollment, usually many parameters need to be set, which is tedious and error-prone to do on the command line. Therefore, the client offers the possibility to read options from sections of the OpenSSL config file, usually called openssl.cnf. The values found there can still be extended and even overridden by any subsequently loaded sections and on the command line.

After including in the configuration file the following sections:

[cmp]\nserver = 127.0.0.1\npath = pkix/\ntrusted = capubs.pem\ncert = cl_cert.pem\nkey = cl_key.pem\nnewkey = cl_key.pem\ncertout = cl_cert.pem\n\n[init]\nrecipient = \"/CN=CMPserver\"\ntrusted =\ncert =\nkey =\nref = 1234\nsecret = pass:1234-5678-1234-567\nsubject = \"/CN=MyName\"\ncacertsout = capubs.pem\n

the above enrollment transactions reduce to

openssl cmp -section cmp,init\nopenssl cmp -cmd kur -newkey cl_key_new.pem\n

and the above transaction using a general message reduces to

openssl cmp -section cmp,init -cmd genm\n
"},{"location":"man1/openssl-cmp/#see-also","title":"SEE ALSO","text":"

openssl-genrsa(1), openssl-ecparam(1), openssl-list(1), openssl-req(1), openssl-x509(1), x509v3_config(5)

"},{"location":"man1/openssl-cmp/#history","title":"HISTORY","text":"

The cmp application was added in OpenSSL 3.0.

The -engine option was deprecated in OpenSSL 3.0.

The -profile option was added in OpenSSL 3.3.

-crlcert, -oldcrl, -crlout, -crlform and -rsp_crl options were added in OpenSSL 3.4.

"},{"location":"man1/openssl-cmp/#copyright","title":"COPYRIGHT","text":"

Copyright 2007-2024 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.

"},{"location":"man1/openssl-cms/","title":"openssl-cms","text":""},{"location":"man1/openssl-cms/#name","title":"NAME","text":"

openssl-cms - CMS command

"},{"location":"man1/openssl-cms/#synopsis","title":"SYNOPSIS","text":"

openssl cms [-help]

General options:

[-in filename] [-out filename] [-config configfile]

Operation options:

[-encrypt] [-decrypt] [-sign] [-verify] [-resign] [-sign_receipt] [-verify_receipt receipt] [-digest digest] [-digest_create] [-digest_verify] [-compress] [-uncompress] [-EncryptedData_encrypt] [-EncryptedData_decrypt] [-data_create] [-data_out] [-cmsout]

File format options:

[-inform DER|PEM|SMIME] [-outform DER|PEM|SMIME] [-rctform DER|PEM|SMIME] [-stream] [-indef] [-noindef] [-binary] [-crlfeol] [-asciicrlf]

Keys and password options:

[-pwri_password password] [-secretkey key] [-secretkeyid id] [-inkey filename|uri] [-passin arg] [-keyopt name:parameter] [-keyform DER|PEM|P12|ENGINE] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-rand files] [-writerand file]

Encryption options:

[-originator file] [-recip file] [recipient-cert ...] [-cipher] [-wrap cipher] [-aes128-wrap] [-aes192-wrap] [-aes256-wrap] [-des3-wrap] [-debug_decrypt]

Signing options:

[-md digest] [-signer file] [-certfile file] [-cades] [-nodetach] [-nocerts] [-noattr] [-nosmimecap] [-receipt_request_all] [-receipt_request_first] [-receipt_request_from emailaddress] [-receipt_request_to emailaddress]

Verification options:

[-signer file] [-content filename] [-no_content_verify] [-no_attr_verify] [-nosigs] [-noverify] [-nointern] [-cades] [-verify_retcode] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore]

Output options:

[-keyid] [-econtent_type type] [-text] [-certsout file] [-to addr] [-from addr] [-subject subj]

Printing options:

[-noout] [-print] [-nameopt option] [-receipt_request_print]

Validation options:

[-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]

"},{"location":"man1/openssl-cms/#description","title":"DESCRIPTION","text":"

This command handles data in CMS format such as S/MIME v3.1 email messages. It can encrypt, decrypt, sign, verify, compress, uncompress, and print messages.

"},{"location":"man1/openssl-cms/#options","title":"OPTIONS","text":"

There are a number of operation options that set the type of operation to be performed: encrypt, decrypt, sign, verify, resign, sign_receipt, verify_receipt, digest_create, digest_verify, compress, uncompress, EncryptedData_encrypt, EncryptedData_decrypt, data_create, data_out, or cmsout. The relevance of the other options depends on the operation type and their meaning may vary according to it.

"},{"location":"man1/openssl-cms/#general-options","title":"General options","text":""},{"location":"man1/openssl-cms/#operation-options","title":"Operation options","text":""},{"location":"man1/openssl-cms/#file-format-options","title":"File format options","text":""},{"location":"man1/openssl-cms/#keys-and-password-options","title":"Keys and password options","text":""},{"location":"man1/openssl-cms/#encryption-and-decryption-options","title":"Encryption and decryption options","text":""},{"location":"man1/openssl-cms/#signing-options","title":"Signing options","text":""},{"location":"man1/openssl-cms/#verification-options","title":"Verification options","text":""},{"location":"man1/openssl-cms/#output-options","title":"Output options","text":""},{"location":"man1/openssl-cms/#printing-options","title":"Printing options","text":""},{"location":"man1/openssl-cms/#validation-options","title":"Validation options","text":""},{"location":"man1/openssl-cms/#notes","title":"NOTES","text":"

The MIME message must be sent without any blank lines between the headers and the output. Some mail programs will automatically add a blank line. Piping the mail directly to sendmail is one way to achieve the correct format.

The supplied message to be signed or encrypted must include the necessary MIME headers or many S/MIME clients won't display it properly (if at all). You can use the -text option to automatically add plain text headers.

A \"signed and encrypted\" message is one where a signed message is then encrypted. This can be produced by encrypting an already signed message: see the examples section.

This version of the program only allows one signer per message but it will verify multiple signers on received messages. Some S/MIME clients choke if a message contains multiple signers. It is possible to sign messages \"in parallel\" by signing an already signed message.

The options -encrypt and -decrypt reflect common usage in S/MIME clients. Strictly speaking these process CMS enveloped data: CMS encrypted data is used for other purposes.

The -resign option uses an existing message digest when adding a new signer. This means that attributes must be present in at least one existing signer using the same message digest or this operation will fail.

The -stream and -indef options enable streaming I/O support. As a result the encoding is BER using indefinite length constructed encoding and no longer DER. Streaming is supported for the -encrypt operation and the -sign operation if the content is not detached.

Streaming is always used for the -sign operation with detached data but since the content is no longer part of the CMS structure the encoding remains DER.

If the -decrypt option is used without a recipient certificate then an attempt is made to locate the recipient by trying each potential recipient in turn using the supplied private key. To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or not and if no recipients match the message is \"decrypted\" using a random key which will typically output garbage. The -debug_decrypt option can be used to disable the MMA attack protection and return an error if no recipient can be found: this option should be used with caution. For a fuller description see CMS_decrypt(3)).

"},{"location":"man1/openssl-cms/#cades-basic-electronic-signature-cades-bes","title":"CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)","text":"

A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains:

"},{"location":"man1/openssl-cms/#exit-codes","title":"EXIT CODES","text":""},{"location":"man1/openssl-cms/#compatibility-with-pkcs7-format","title":"COMPATIBILITY WITH PKCS#7 FORMAT","text":"

openssl-smime(1) can only process the older PKCS#7 format. openssl cms supports Cryptographic Message Syntax format. Use of some features will result in messages which cannot be processed by applications which only support the older format. These are detailed below.

The use of the -keyid option with -sign or -encrypt.

The -outform PEM option uses different headers.

The -compress option.

The -secretkey option when used with -encrypt.

The use of PSS with -sign.

The use of OAEP or non-RSA keys with -encrypt.

Additionally the -EncryptedData_create and -data_create type cannot be processed by the older openssl-smime(1) command.

"},{"location":"man1/openssl-cms/#examples","title":"EXAMPLES","text":"

Create a cleartext signed message:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem\n

Create an opaque signed message

openssl cms -sign -in message.txt -text -out mail.msg -nodetach \\\n       -signer mycert.pem\n

Create a signed message, include some additional certificates and read the private key from another file:

openssl cms -sign -in in.txt -text -out mail.msg \\\n       -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem\n

Create a signed message with two signers, use key identifier:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -signer othercert.pem -keyid\n

Send a signed message under Unix directly to sendmail, including headers:

openssl cms -sign -in in.txt -text -signer mycert.pem \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed message\" | sendmail someone@somewhere\n

Verify a message and extract the signer's certificate if successful:

openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt\n

Send encrypted mail using triple DES:

openssl cms -encrypt -in in.txt -from steve@openssl.org \\\n       -to someone@somewhere -subject \"Encrypted message\" \\\n       -des3 user.pem -out mail.msg\n

Sign and encrypt mail:

openssl cms -sign -in ml.txt -signer my.pem -text \\\n       | openssl cms -encrypt -out mail.msg \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed and Encrypted message\" -des3 user.pem\n

Note: the encryption command does not include the -text option because the message being encrypted already has MIME headers.

Decrypt a message:

openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem\n

The output from Netscape form signing is a PKCS#7 structure with the detached signature format. You can use this program to verify the signature by line wrapping the base64 encoded structure and surrounding it with:

-----BEGIN PKCS7-----\n-----END PKCS7-----\n

and using the command,

openssl cms -verify -inform PEM -in signature.pem -content content.txt\n

alternatively you can base64 decode the signature and use

openssl cms -verify -inform DER -in signature.der -content content.txt\n

Create an encrypted message using 128 bit Camellia:

openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem\n

Add a signer to an existing message:

openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg\n

Sign a message using RSA-PSS:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -keyopt rsa_padding_mode:pss\n

Create an encrypted message using RSA-OAEP:

openssl cms -encrypt -in plain.txt -out mail.msg \\\n       -recip cert.pem -keyopt rsa_padding_mode:oaep\n

Use SHA256 KDF with an ECDH certificate:

openssl cms -encrypt -in plain.txt -out mail.msg \\\n       -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256\n

Print CMS signed binary data in human-readable form:

openssl cms -in signed.cms -binary -inform DER -cmsout -print

"},{"location":"man1/openssl-cms/#bugs","title":"BUGS","text":"

The MIME parser isn't very clever: it seems to handle most messages that I've thrown at it but it may choke on others.

The code currently will only write out the signer's certificate to a file: if the signer has a separate encryption certificate this must be manually extracted. There should be some heuristic that determines the correct encryption certificate.

Ideally a database should be maintained of a certificates for each email address.

The code doesn't currently take note of the permitted symmetric encryption algorithms as supplied in the SMIMECapabilities signed attribute. this means the user has to manually include the correct encryption algorithm. It should store the list of permitted ciphers in a database and only use those.

No revocation checking is done on the signer's certificate.

"},{"location":"man1/openssl-cms/#see-also","title":"SEE ALSO","text":"

ossl_store-file(7)

"},{"location":"man1/openssl-cms/#history","title":"HISTORY","text":"

The default encryption cipher was changed from 3DES to AES-256 in OpenSSL 3.5.

The use of multiple -signer options and the -resign command were first added in OpenSSL 1.0.0.

The -keyopt option was added in OpenSSL 1.0.2.

Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2.

The use of non-RSA keys with -encrypt and -decrypt was added in OpenSSL 1.0.2.

The -no_alt_chains option was added in OpenSSL 1.0.2b.

The -nameopt option was added in OpenSSL 3.0.0.

The -engine option was deprecated in OpenSSL 3.0.

The -digest option was added in OpenSSL 3.2.

"},{"location":"man1/openssl-cms/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2024 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.

"},{"location":"man1/openssl-crl/","title":"openssl-crl","text":""},{"location":"man1/openssl-crl/#name","title":"NAME","text":"

openssl-crl - CRL command

"},{"location":"man1/openssl-crl/#synopsis","title":"SYNOPSIS","text":"

openssl crl [-help] [-inform DER|PEM] [-outform DER|PEM] [-key filename] [-keyform DER|PEM|P12] [-dateopt] [-text] [-in filename] [-out filename] [-gendelta filename] [-badsig] [-verify] [-noout] [-hash] [-hash_old] [-fingerprint] [-crlnumber] [-issuer] [-lastupdate] [-nextupdate] [-nameopt option] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-crl/#description","title":"DESCRIPTION","text":"

This command processes CRL files in DER or PEM format.

"},{"location":"man1/openssl-crl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-crl/#examples","title":"EXAMPLES","text":"

Convert a CRL file from PEM to DER:

openssl crl -in crl.pem -outform DER -out crl.der\n

Output the text form of a DER encoded certificate:

openssl crl -in crl.der -text -noout\n
"},{"location":"man1/openssl-crl/#bugs","title":"BUGS","text":"

Ideally it should be possible to create a CRL using appropriate options and files too.

"},{"location":"man1/openssl-crl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl2pkcs7(1), openssl-ca(1), openssl-x509(1), ossl_store-file(7)

"},{"location":"man1/openssl-crl/#history","title":"HISTORY","text":"

Since OpenSSL 3.3, the -verify option will exit with 1 on failure.

"},{"location":"man1/openssl-crl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-crl2pkcs7/","title":"openssl-crl2pkcs7","text":""},{"location":"man1/openssl-crl2pkcs7/#name","title":"NAME","text":"

openssl-crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates

"},{"location":"man1/openssl-crl2pkcs7/#synopsis","title":"SYNOPSIS","text":"

openssl crl2pkcs7 [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-certfile filename] [-nocrl] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-crl2pkcs7/#description","title":"DESCRIPTION","text":"

This command takes an optional CRL and one or more certificates and converts them into a PKCS#7 degenerate \"certificates only\" structure.

"},{"location":"man1/openssl-crl2pkcs7/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-crl2pkcs7/#examples","title":"EXAMPLES","text":"

Create a PKCS#7 structure from a certificate and CRL:

openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem\n

Creates a PKCS#7 structure in DER format with no CRL from several different certificates:

openssl crl2pkcs7 -nocrl -certfile newcert.pem\n       -certfile demoCA/cacert.pem -outform DER -out p7.der\n
"},{"location":"man1/openssl-crl2pkcs7/#notes","title":"NOTES","text":"

The output file is a PKCS#7 signed data structure containing no signers and just certificates and an optional CRL.

This command can be used to send certificates and CAs to Netscape as part of the certificate enrollment process. This involves sending the DER encoded output as MIME type application/x-x509-user-cert.

The PEM encoded form with the header and footer lines removed can be used to install user certificates and CAs in MSIE using the Xenroll control.

"},{"location":"man1/openssl-crl2pkcs7/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkcs7(1)

"},{"location":"man1/openssl-crl2pkcs7/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-dgst/","title":"openssl-dgst","text":""},{"location":"man1/openssl-dgst/#name","title":"NAME","text":"

openssl-dgst - perform digest operations

"},{"location":"man1/openssl-dgst/#synopsis","title":"SYNOPSIS","text":"

openssl dgst|digest [-digest] [-list] [-help] [-c] [-d] [-debug] [-hex] [-binary] [-xoflen length] [-r] [-out filename] [-sign filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-verify filename] [-prverify filename] [-signature filename] [-sigopt nm:v] [-hmac key] [-mac alg] [-macopt nm:v] [-fips-fingerprint] [-engine id] [-engine_impl id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [file ...]

"},{"location":"man1/openssl-dgst/#description","title":"DESCRIPTION","text":"

This command output the message digest of a supplied file or files in hexadecimal, and also generates and verifies digital signatures using message digests.

The generic name, openssl dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256. A supported digest name may also be used as the sub-command name. To see the list of supported algorithms, use openssl list -digest-algorithms

"},{"location":"man1/openssl-dgst/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dgst/#examples","title":"EXAMPLES","text":"

To create a hex-encoded message digest of a file:

openssl dgst -md5 -hex file.txt\nor\nopenssl md5 file.txt\n

To sign a file using SHA-256 with binary file output:

openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt\nor\nopenssl sha256 -sign privatekey.pem -out signature.sign file.txt\n

To verify a signature:

openssl dgst -sha256 -verify publickey.pem \\\n-signature signature.sign \\\nfile.txt\n
"},{"location":"man1/openssl-dgst/#notes","title":"NOTES","text":"

The digest mechanisms that are available will depend on the options used when building OpenSSL. The openssl list -digest-algorithms command can be used to list them.

New or agile applications should use probably use SHA-256. Other digests, particularly SHA-1 and MD5, are still widely used for interoperating with existing formats and protocols.

When signing a file, this command will automatically determine the algorithm (RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. When verifying signatures, it only handles the RSA, DSA, or ECDSA signature itself, not the related data to identify the signer and algorithm used in formats such as x.509, CMS, and S/MIME.

A source of random numbers is required for certain signing algorithms, in particular ECDSA and DSA.

The signing and verify options should only be used if a single file is being signed or verified.

Hex signatures cannot be verified using openssl. Instead, use \"xxd -r\" or similar program to transform the hex signature into a binary signature prior to verification.

The openssl-mac(1) command is preferred over the -hmac, -mac and -macopt command line options.

"},{"location":"man1/openssl-dgst/#see-also","title":"SEE ALSO","text":"

openssl-mac(1)

"},{"location":"man1/openssl-dgst/#history","title":"HISTORY","text":"

The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0. The FIPS-related options were removed in OpenSSL 1.1.0.

The -engine and -engine_impl options were deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-dgst/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-dhparam/","title":"openssl-dhparam","text":""},{"location":"man1/openssl-dhparam/#name","title":"NAME","text":"

openssl-dhparam - DH parameter manipulation and generation

"},{"location":"man1/openssl-dhparam/#synopsis","title":"SYNOPSIS","text":"

openssl dhparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-dsaparam] [-check] [-noout] [-text] [-verbose] [-quiet] [-2] [-3] [-5] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [numbits]

"},{"location":"man1/openssl-dhparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate DH parameter files.

See \"EXAMPLES\" in openssl-genpkey(1) for examples on how to generate a key using a named safe prime group without generating intermediate parameters.

"},{"location":"man1/openssl-dhparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dhparam/#notes","title":"NOTES","text":"

This command replaces the dh and gendh commands of previous releases.

"},{"location":"man1/openssl-dhparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-dsaparam(1), openssl-genpkey(1).

"},{"location":"man1/openssl-dhparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-dhparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-dsa/","title":"openssl-dsa","text":""},{"location":"man1/openssl-dsa/#name","title":"NAME","text":"

openssl-dsa - DSA key processing

"},{"location":"man1/openssl-dsa/#synopsis","title":"SYNOPSIS","text":"

openssl dsa [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-text] [-noout] [-modulus] [-pubin] [-pubout] [-pvk-strong] [-pvk-weak] [-pvk-none] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-dsa/#description","title":"DESCRIPTION","text":"

This command processes DSA keys. They can be converted between various forms and their components printed out. Note This command uses the traditional SSLeay compatible format for private key encryption: newer applications should use the more secure PKCS#8 format using the pkcs8

"},{"location":"man1/openssl-dsa/#options","title":"OPTIONS","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-dsa/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To remove the pass phrase on a DSA private key:

openssl dsa -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl dsa -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl dsa -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl dsa -in key.pem -text -noout\n

To just output the public part of a private key:

openssl dsa -in key.pem -pubout -out pubkey.pem\n
"},{"location":"man1/openssl-dsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-dsaparam(1), openssl-gendsa(1), openssl-rsa(1), openssl-genrsa(1)

"},{"location":"man1/openssl-dsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-dsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-dsaparam/","title":"openssl-dsaparam","text":""},{"location":"man1/openssl-dsaparam/#name","title":"NAME","text":"

openssl-dsaparam - DSA parameter manipulation and generation

"},{"location":"man1/openssl-dsaparam/#synopsis","title":"SYNOPSIS","text":"

openssl dsaparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-noout] [-text] [-genkey] [-verbose] [-quiet] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [numbits] [numqbits]

"},{"location":"man1/openssl-dsaparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate or generate DSA parameter files.

DSA parameter generation can be a slow process and as a result the same set of DSA parameters is often used to generate several distinct keys.

"},{"location":"man1/openssl-dsaparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dsaparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-gendsa(1), openssl-dsa(1), openssl-genrsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-dsaparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-dsaparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-ec/","title":"openssl-ec","text":""},{"location":"man1/openssl-ec/#name","title":"NAME","text":"

openssl-ec - EC key processing

"},{"location":"man1/openssl-ec/#synopsis","title":"SYNOPSIS","text":"

openssl ec [-help] [-inform DER|PEM|P12|ENGINE] [-outform DER|PEM] [-in filename|uri] [-passin arg] [-out filename] [-passout arg] [-des] [-des3] [-idea] [-text] [-noout] [-param_out] [-pubin] [-pubout] [-conv_form arg] [-param_enc arg] [-no_public] [-check] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ec/#description","title":"DESCRIPTION","text":"

The openssl-ec(1) command processes EC keys. They can be converted between various forms and their components printed out. Note OpenSSL uses the private key format specified in 'SEC 1: Elliptic Curve Cryptography' (http://www.secg.org/). To convert an OpenSSL EC private key into the PKCS#8 private key format use the openssl-pkcs8(1) command.

"},{"location":"man1/openssl-ec/#options","title":"OPTIONS","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-ec/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To encrypt a private key using triple DES:

openssl ec -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl ec -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl ec -in key.pem -text -noout\n

To just output the public part of a private key:

openssl ec -in key.pem -pubout -out pubkey.pem\n

To change the parameters encoding to explicit:

openssl ec -in key.pem -param_enc explicit -out keyout.pem\n

To change the point conversion form to compressed:

openssl ec -in key.pem -conv_form compressed -out keyout.pem\n
"},{"location":"man1/openssl-ec/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-ecparam(1), openssl-dsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-ec/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -conv_form and -no_public options are no longer supported with keys loaded from an engine in OpenSSL 3.0.

"},{"location":"man1/openssl-ec/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2023 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.

"},{"location":"man1/openssl-ecparam/","title":"openssl-ecparam","text":""},{"location":"man1/openssl-ecparam/#name","title":"NAME","text":"

openssl-ecparam - EC parameter manipulation and generation

"},{"location":"man1/openssl-ecparam/#synopsis","title":"SYNOPSIS","text":"

openssl ecparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-noout] [-text] [-check] [-check_named] [-name arg] [-list_curves] [-conv_form arg] [-param_enc arg] [-no_seed] [-genkey] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ecparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate or generate EC parameter files.

OpenSSL is currently not able to generate new groups and therefore this command can only create EC parameters from known (named) curves.

"},{"location":"man1/openssl-ecparam/#options","title":"OPTIONS","text":"

The openssl-genpkey(1) and openssl-pkeyparam(1) commands are capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-ecparam/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-genpkey(1) and openssl-pkeyparam(1) commands contains examples equivalent to the ones listed here.

To create EC parameters with the group 'prime192v1':

openssl ecparam -out ec_param.pem -name prime192v1\n

To create EC parameters with explicit parameters:

openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit\n

To validate given EC parameters:

openssl ecparam -in ec_param.pem -check\n

To create EC parameters and a private key:

openssl ecparam -out ec_key.pem -name prime192v1 -genkey\n

To change the point encoding to 'compressed':

openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed\n

To print out the EC parameters to standard output:

openssl ecparam -in ec_param.pem -noout -text\n
"},{"location":"man1/openssl-ecparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-genpkey(1), openssl-ec(1), openssl-dsaparam(1)

"},{"location":"man1/openssl-ecparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-ecparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2021 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.

"},{"location":"man1/openssl-enc/","title":"openssl-enc","text":""},{"location":"man1/openssl-enc/#name","title":"NAME","text":"

openssl-enc - symmetric cipher routines

"},{"location":"man1/openssl-enc/#synopsis","title":"SYNOPSIS","text":"

openssl enc|cipher [-cipher] [-help] [-list] [-ciphers] [-in filename] [-out filename] [-pass arg] [-e] [-d] [-a] [-base64] [-A] [-k password] [-kfile filename] [-K key] [-iv IV] [-S salt] [-salt] [-nosalt] [-z] [-md digest] [-iter count] [-pbkdf2] [-saltlen size] [-p] [-P] [-bufsize number] [-nopad] [-v] [-debug] [-none] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

openssl cipher [...]

"},{"location":"man1/openssl-enc/#description","title":"DESCRIPTION","text":"

The symmetric cipher commands allow data to be encrypted or decrypted using various block and stream ciphers using keys based on passwords or explicitly provided. Base64 encoding or decoding can also be performed either by itself or in addition to the encryption or decryption.

"},{"location":"man1/openssl-enc/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-enc/#notes","title":"NOTES","text":"

The program can be called either as openssl _cipher_ or openssl enc -_cipher_. The first form doesn't work with engine-provided ciphers, because this form is processed before the configuration file is read and any ENGINEs loaded. Use the openssl-list(1) command to get a list of supported ciphers.

Engines which provide entirely new encryption algorithms (such as the ccgost engine which provides gost89 algorithm) should be configured in the configuration file. Engines specified on the command line using -engine option can only be used for hardware-assisted implementations of ciphers which are supported by the OpenSSL core or another engine specified in the configuration file.

When the enc command lists supported ciphers, ciphers provided by engines, specified in the configuration files are listed too.

A password will be prompted for to derive the key and IV if necessary.

The -salt option should ALWAYS be used if the key is being derived from a password unless you want compatibility with previous versions of OpenSSL.

Without the -salt option it is possible to perform efficient dictionary attacks on the password and to attack stream cipher encrypted data. The reason for this is that without the salt the same password always generates the same encryption key.

When the salt is generated at random (that means when encrypting using a passphrase without explicit salt given using -S option), the first bytes of the encrypted data are reserved to store the salt for later decrypting.

Some of the ciphers do not have large keys and others have security implications if not used correctly. A beginner is advised to just use a strong block cipher, such as AES, in CBC mode.

All the block ciphers normally use PKCS#5 padding, also known as standard block padding. This allows a rudimentary integrity or password check to be performed. However, since the chance of random data passing the test is better than 1 in 256 it isn't a very good test.

If padding is disabled then the input data must be a multiple of the cipher block length.

All RC2 ciphers have the same key and effective key length.

Blowfish and RC5 algorithms use a 128 bit key.

Please note that OpenSSL 3.0 changed the effect of the -S option. Any explicit salt value specified via this option is no longer prepended to the ciphertext when encrypting, and must again be explicitly provided when decrypting. Conversely, when the -S option is used during decryption, the ciphertext is expected to not have a prepended salt value.

When using OpenSSL 3.0 or later to decrypt data that was encrypted with an explicit salt under OpenSSL 1.1.1 do not use the -S option, the salt will then be read from the ciphertext. To generate ciphertext that can be decrypted with OpenSSL 1.1.1 do not use the -S option, the salt will be then be generated randomly and prepended to the output.

"},{"location":"man1/openssl-enc/#supported-ciphers","title":"SUPPORTED CIPHERS","text":"

Note that some of these ciphers can be disabled at compile time and some are available only if an appropriate engine is configured in the configuration file. The output when invoking this command with the -list option (that is openssl enc -list) is a list of ciphers, supported by your version of OpenSSL, including ones provided by configured engines.

This command does not support authenticated encryption modes like CCM and GCM, and will not support such modes in the future. This is due to having to begin streaming output (e.g., to standard output when -out is not used) before the authentication tag could be validated. When this command is used in a pipeline, the receiving end will not be able to roll back upon authentication failure. The AEAD modes currently in common use also suffer from catastrophic failure of confidentiality and/or integrity upon reuse of key/iv/nonce, and since openssl enc places the entire burden of key/iv/nonce management upon the user, the risk of exposing AEAD modes is too great to allow. These key/iv/nonce management issues also affect other modes currently exposed in this command, but the failure modes are less extreme in these cases, and the functionality cannot be removed with a stable release branch. For bulk encryption of data, whether using authenticated encryption modes or other modes, openssl-cms(1) is recommended, as it provides a standard data format and performs the needed key/iv/nonce management.

When enc is used with key wrapping modes the input data cannot be streamed, meaning it must be processed in a single pass. Consequently, the input data size must be less than the buffer size (-bufsize arg, default to 8*1024 bytes). The '*-wrap' ciphers require the input to be a multiple of 8 bytes long, because no padding is involved. The '*-wrap-pad' ciphers allow any input length. In both cases, no IV is needed. See example below.

base64             Base 64\n\nbf-cbc             Blowfish in CBC mode\nbf                 Alias for bf-cbc\nblowfish           Alias for bf-cbc\nbf-cfb             Blowfish in CFB mode\nbf-ecb             Blowfish in ECB mode\nbf-ofb             Blowfish in OFB mode\n\ncast-cbc           CAST in CBC mode\ncast               Alias for cast-cbc\ncast5-cbc          CAST5 in CBC mode\ncast5-cfb          CAST5 in CFB mode\ncast5-ecb          CAST5 in ECB mode\ncast5-ofb          CAST5 in OFB mode\n\nchacha20           ChaCha20 algorithm\n\ndes-cbc            DES in CBC mode\ndes                Alias for des-cbc\ndes-cfb            DES in CFB mode\ndes-ofb            DES in OFB mode\ndes-ecb            DES in ECB mode\n\ndes-ede-cbc        Two key triple DES EDE in CBC mode\ndes-ede            Two key triple DES EDE in ECB mode\ndes-ede-cfb        Two key triple DES EDE in CFB mode\ndes-ede-ofb        Two key triple DES EDE in OFB mode\n\ndes-ede3-cbc       Three key triple DES EDE in CBC mode\ndes-ede3           Three key triple DES EDE in ECB mode\ndes3               Alias for des-ede3-cbc\ndes-ede3-cfb       Three key triple DES EDE CFB mode\ndes-ede3-ofb       Three key triple DES EDE in OFB mode\n\ndesx               DESX algorithm.\n\ngost89             GOST 28147-89 in CFB mode (provided by ccgost engine)\ngost89-cnt         GOST 28147-89 in CNT mode (provided by ccgost engine)\n\nidea-cbc           IDEA algorithm in CBC mode\nidea               same as idea-cbc\nidea-cfb           IDEA in CFB mode\nidea-ecb           IDEA in ECB mode\nidea-ofb           IDEA in OFB mode\n\nrc2-cbc            128 bit RC2 in CBC mode\nrc2                Alias for rc2-cbc\nrc2-cfb            128 bit RC2 in CFB mode\nrc2-ecb            128 bit RC2 in ECB mode\nrc2-ofb            128 bit RC2 in OFB mode\nrc2-64-cbc         64 bit RC2 in CBC mode\nrc2-40-cbc         40 bit RC2 in CBC mode\n\nrc4                128 bit RC4\nrc4-64             64 bit RC4\nrc4-40             40 bit RC4\n\nrc5-cbc            RC5 cipher in CBC mode\nrc5                Alias for rc5-cbc\nrc5-cfb            RC5 cipher in CFB mode\nrc5-ecb            RC5 cipher in ECB mode\nrc5-ofb            RC5 cipher in OFB mode\n\nseed-cbc           SEED cipher in CBC mode\nseed               Alias for seed-cbc\nseed-cfb           SEED cipher in CFB mode\nseed-ecb           SEED cipher in ECB mode\nseed-ofb           SEED cipher in OFB mode\n\nsm4-cbc            SM4 cipher in CBC mode\nsm4                Alias for sm4-cbc\nsm4-cfb            SM4 cipher in CFB mode\nsm4-ctr            SM4 cipher in CTR mode\nsm4-ecb            SM4 cipher in ECB mode\nsm4-ofb            SM4 cipher in OFB mode\n\naes-[128|192|256]-cbc  128/192/256 bit AES in CBC mode\naes[128|192|256]       Alias for aes-[128|192|256]-cbc\naes-[128|192|256]-cfb  128/192/256 bit AES in 128 bit CFB mode\naes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode\naes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode\naes-[128|192|256]-ctr  128/192/256 bit AES in CTR mode\naes-[128|192|256]-ecb  128/192/256 bit AES in ECB mode\naes-[128|192|256]-ofb  128/192/256 bit AES in OFB mode\n\naes-[128|192|256]-wrap     key wrapping using 128/192/256 bit AES\naes-[128|192|256]-wrap-pad key wrapping with padding using 128/192/256 bit AES\n\naria-[128|192|256]-cbc  128/192/256 bit ARIA in CBC mode\naria[128|192|256]       Alias for aria-[128|192|256]-cbc\naria-[128|192|256]-cfb  128/192/256 bit ARIA in 128 bit CFB mode\naria-[128|192|256]-cfb1 128/192/256 bit ARIA in 1 bit CFB mode\naria-[128|192|256]-cfb8 128/192/256 bit ARIA in 8 bit CFB mode\naria-[128|192|256]-ctr  128/192/256 bit ARIA in CTR mode\naria-[128|192|256]-ecb  128/192/256 bit ARIA in ECB mode\naria-[128|192|256]-ofb  128/192/256 bit ARIA in OFB mode\n\ncamellia-[128|192|256]-cbc  128/192/256 bit Camellia in CBC mode\ncamellia[128|192|256]       Alias for camellia-[128|192|256]-cbc\ncamellia-[128|192|256]-cfb  128/192/256 bit Camellia in 128 bit CFB mode\ncamellia-[128|192|256]-cfb1 128/192/256 bit Camellia in 1 bit CFB mode\ncamellia-[128|192|256]-cfb8 128/192/256 bit Camellia in 8 bit CFB mode\ncamellia-[128|192|256]-ctr  128/192/256 bit Camellia in CTR mode\ncamellia-[128|192|256]-ecb  128/192/256 bit Camellia in ECB mode\ncamellia-[128|192|256]-ofb  128/192/256 bit Camellia in OFB mode\n
"},{"location":"man1/openssl-enc/#examples","title":"EXAMPLES","text":"

Just base64 encode a binary file:

openssl base64 -in file.bin -out file.b64\n

Decode the same file

openssl base64 -d -in file.b64 -out file.bin\n

Encrypt a file using AES-128 using a prompted password and PBKDF2 key derivation:

openssl enc -aes128 -pbkdf2 -in file.txt -out file.aes128\n

Decrypt a file using a supplied password:

openssl enc -aes128 -pbkdf2 -d -in file.aes128 -out file.txt \\\n   -pass pass:<password>\n

Encrypt a file then base64 encode it (so it can be sent via mail for example) using AES-256 in CTR mode and PBKDF2 key derivation:

openssl enc -aes-256-ctr -pbkdf2 -a -in file.txt -out file.aes256\n

Base64 decode a file then decrypt it using a password supplied in a file:

openssl enc -aes-256-ctr -pbkdf2 -d -a -in file.aes256 -out file.txt \\\n   -pass file:<passfile>\n

AES key wrapping:

openssl enc -e -a -id-aes128-wrap-pad -K 000102030405060708090A0B0C0D0E0F -in file.bin\n

or openssl aes128-wrap-pad -e -a -K 000102030405060708090A0B0C0D0E0F -in file.bin

"},{"location":"man1/openssl-enc/#bugs","title":"BUGS","text":"

The -A option when used with large files doesn't work properly. On the other hand, when base64 decoding without the -A option, if the first 1024 bytes of input do not include a newline character the first two lines of input are ignored.

The openssl enc command only supports a fixed number of algorithms with certain parameters. So if, for example, you want to use RC2 with a 76 bit key or RC4 with an 84 bit key you can't use this program.

"},{"location":"man1/openssl-enc/#history","title":"HISTORY","text":"

The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.

The -list option was added in OpenSSL 1.1.1e.

The -ciphers and -engine options were deprecated in OpenSSL 3.0.

The -saltlen option was added in OpenSSL 3.2.

"},{"location":"man1/openssl-enc/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-engine/","title":"openssl-engine","text":""},{"location":"man1/openssl-engine/#name","title":"NAME","text":"

openssl-engine - load and query engines

"},{"location":"man1/openssl-engine/#synopsis","title":"SYNOPSIS","text":"

openssl engine [-help] [-v] [-vv] [-vvv] [-vvvv] [-c] [-t] [-tt] [-pre command] ... [-post command] ... [engine ...]

"},{"location":"man1/openssl-engine/#description","title":"DESCRIPTION","text":"

This command has been deprecated. Providers should be used instead of engines.

This command is used to query the status and capabilities of the specified _engine_s. Engines may be specified before and after all other command-line flags. Only those specified are queried.

"},{"location":"man1/openssl-engine/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-engine/#examples","title":"EXAMPLES","text":"

To list all the commands available to a dynamic engine:

$ openssl engine -t -tt -vvvv dynamic\n(dynamic) Dynamic engine loading support\n     [ unavailable ]\n     SO_PATH: Specifies the path to the new ENGINE shared library\n          (input flags): STRING\n     NO_VCHECK: Specifies to continue even if version checking fails (boolean)\n          (input flags): NUMERIC\n     ID: Specifies an ENGINE id name for loading\n          (input flags): STRING\n     LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)\n          (input flags): NUMERIC\n     DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)\n          (input flags): NUMERIC\n     DIR_ADD: Adds a directory from which ENGINEs can be loaded\n          (input flags): STRING\n     LOAD: Load up the ENGINE specified by other settings\n          (input flags): NO_INPUT\n

To list the capabilities of the rsax engine:

$ openssl engine -c\n(rsax) RSAX engine support\n [RSA]\n(dynamic) Dynamic engine loading support\n
"},{"location":"man1/openssl-engine/#environment","title":"ENVIRONMENT","text":""},{"location":"man1/openssl-engine/#see-also","title":"SEE ALSO","text":"

openssl(1), config(5)

"},{"location":"man1/openssl-engine/#history","title":"HISTORY","text":"

This command was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-engine/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-errstr/","title":"openssl-errstr","text":""},{"location":"man1/openssl-errstr/#name","title":"NAME","text":"

openssl-errstr - lookup error codes

"},{"location":"man1/openssl-errstr/#synopsis","title":"SYNOPSIS","text":"

openssl errstr [-help] error_code...

"},{"location":"man1/openssl-errstr/#description","title":"DESCRIPTION","text":"

Sometimes an application will not load error message texts and only numerical forms will be available. This command can be used to display the meaning of the hex code. The hex code is the hex digits after the second colon.

"},{"location":"man1/openssl-errstr/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-errstr/#examples","title":"EXAMPLES","text":"

The error code:

27594:error:2006D080:lib(32)::reason(128)::107:\n

can be displayed with:

openssl errstr 2006D080\n

to produce the error message:

error:2006D080:BIO routines::no such file\n
"},{"location":"man1/openssl-errstr/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-fipsinstall/","title":"openssl-fipsinstall","text":""},{"location":"man1/openssl-fipsinstall/#name","title":"NAME","text":"

openssl-fipsinstall - perform FIPS configuration installation

"},{"location":"man1/openssl-fipsinstall/#synopsis","title":"SYNOPSIS","text":"

openssl fipsinstall [-help] [-in configfilename] [-out configfilename] [-module modulefilename] [-provider_name providername] [-section_name sectionname] [-verify] [-mac_name macname] [-macopt nm:v] [-noout] [-quiet] [-pedantic] [-no_conditional_errors] [-no_security_checks] [-hmac_key_check] [-kmac_key_check] [-ems_check] [-no_drbg_truncated_digests] [-signature_digest_check] [-hkdf_digest_check] [-tls13_kdf_digest_check] [-tls1_prf_digest_check] [-sshkdf_digest_check] [-sskdf_digest_check] [-x963kdf_digest_check] [-dsa_sign_disabled] [-no_pbkdf2_lower_bound_check] [-no_short_mac] [-tdes_encrypt_disabled] [-rsa_pkcs15_padding_disabled] [-rsa_pss_saltlen_check] [-rsa_sign_x931_disabled] [-hkdf_key_check] [-kbkdf_key_check] [-tls13_kdf_key_check] [-tls1_prf_key_check] [-sshkdf_key_check] [-sskdf_key_check] [-x963kdf_key_check] [-x942kdf_key_check] [-ecdh_cofactor_check] [-self_test_onload] [-self_test_oninstall] [-corrupt_desc selftest_description] [-corrupt_type selftest_type] [-config parent_config]

"},{"location":"man1/openssl-fipsinstall/#description","title":"DESCRIPTION","text":"

This command is used to generate a FIPS module configuration file. This configuration file can be used each time a FIPS module is loaded in order to pass data to the FIPS module self tests. The FIPS module always verifies its MAC, but optionally only needs to run the KAT's once, at installation.

The generated configuration file consists of:

This file is described in fips_config(5).

"},{"location":"man1/openssl-fipsinstall/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-fipsinstall/#notes","title":"NOTES","text":"

Self tests results are logged by default if the options -quiet and -noout are not specified, or if either of the options -corrupt_desc or -corrupt_type are used. If the base configuration file is set up to autoload the fips module, then the fips module will be loaded and self tested BEFORE the fipsinstall application has a chance to set up its own self test callback. As a result of this the self test output and the options -corrupt_desc and -corrupt_type will be ignored. For normal usage the base configuration file should use the default provider when generating the fips configuration file.

The -self_test_oninstall option was added and the -self_test_onload option was made the default in OpenSSL 3.1.

The command and all remaining options were added in OpenSSL 3.0.

"},{"location":"man1/openssl-fipsinstall/#examples","title":"EXAMPLES","text":"

Calculate the mac of a FIPS module fips.so and run a FIPS self test for the module, and save the fips.cnf configuration file:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips\n

Verify that the configuration file fips.cnf contains the correct info:

openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify\n

Corrupt any self tests which have the description SHA1:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \\\n        -corrupt_desc 'SHA1'\n

Validate that the fips module can be loaded from a base configuration file:

export OPENSSL_CONF_INCLUDE=<path of configuration files>\nexport OPENSSL_MODULES=<provider-path>\nopenssl fipsinstall -config' 'default.cnf'\n
"},{"location":"man1/openssl-fipsinstall/#see-also","title":"SEE ALSO","text":"

config(5), fips_config(5), OSSL_PROVIDER-FIPS(7), EVP_MAC(3)

"},{"location":"man1/openssl-fipsinstall/#history","title":"HISTORY","text":"

The openssl-fipsinstall application was added in OpenSSL 3.0.

The following options were added in OpenSSL 3.1:

-ems_check, -self_test_oninstall

The following options were added in OpenSSL 3.2:

-pedantic, -no_drbg_truncated_digests

The following options were added in OpenSSL 3.4:

-hmac_key_check, -kmac_key_check, -signature_digest_check, -hkdf_digest_check, -tls13_kdf_digest_check, -tls1_prf_digest_check, -sshkdf_digest_check, -sskdf_digest_check, -x963kdf_digest_check, -dsa_sign_disabled, -no_pbkdf2_lower_bound_check, -no_short_mac, -tdes_encrypt_disabled, -rsa_pkcs15_padding_disabled, -rsa_pss_saltlen_check, -rsa_sign_x931_disabled, -hkdf_key_check, -kbkdf_key_check, -tls13_kdf_key_check, -tls1_prf_key_check, -sshkdf_key_check, -sskdf_key_check, -x963kdf_key_check, -x942kdf_key_check, -ecdh_cofactor_check

"},{"location":"man1/openssl-fipsinstall/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man1/openssl-format-options/","title":"openssl-format-options","text":""},{"location":"man1/openssl-format-options/#name","title":"NAME","text":"

openssl-format-options - OpenSSL command input and output format options

"},{"location":"man1/openssl-format-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-format-options/#description","title":"DESCRIPTION","text":"

Several OpenSSL commands can take input or generate output in a variety of formats.

Since OpenSSL 3.0 keys, single certificates, and CRLs can be read from files in any of the DER, PEM or P12 formats. Specifying their input format is no more needed and the openssl commands will automatically try all the possible formats. However if the DER or PEM input format is specified it will be enforced.

In order to access a key via an engine the input format ENGINE may be used; alternatively the key identifier in the <uri> argument of the respective key option may be preceded by org.openssl.engine:. See \"Engine Options\" in openssl(1) for an example usage of the latter.

"},{"location":"man1/openssl-format-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-format-options/#format-options","title":"Format Options","text":"

The options to specify the format are as follows. Refer to the individual man page to see which options are accepted.

"},{"location":"man1/openssl-format-options/#format-option-arguments","title":"Format Option Arguments","text":"

The possible format arguments are described below. Both uppercase and lowercase are accepted.

The list of acceptable format arguments, and the default, is described in each command documentation.

"},{"location":"man1/openssl-format-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-gendsa/","title":"openssl-gendsa","text":""},{"location":"man1/openssl-gendsa/#name","title":"NAME","text":"

openssl-gendsa - generate a DSA private key from a set of parameters

"},{"location":"man1/openssl-gendsa/#synopsis","title":"SYNOPSIS","text":"

openssl gendsa [-help] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-verbose] [-quiet] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [paramfile]

"},{"location":"man1/openssl-gendsa/#description","title":"DESCRIPTION","text":"

This command generates a DSA private key from a DSA parameter file (which will be typically generated by the openssl-dsaparam(1) command).

"},{"location":"man1/openssl-gendsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-gendsa/#notes","title":"NOTES","text":"

DSA key generation is little more than random number generation so it is much quicker that RSA key generation for example.

"},{"location":"man1/openssl-gendsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-dsaparam(1), openssl-dsa(1), openssl-genrsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-gendsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-gendsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-genpkey/","title":"openssl-genpkey","text":""},{"location":"man1/openssl-genpkey/#name","title":"NAME","text":"

openssl-genpkey - generate a private key or key pair

"},{"location":"man1/openssl-genpkey/#synopsis","title":"SYNOPSIS","text":"

openssl genpkey [-help] [-out filename] [-outpubkey filename] [-outform DER|PEM] [-verbose] [-quiet] [-pass arg] [-cipher] [-paramfile file] [-algorithm alg] [-pkeyopt opt:value] [-genparam] [-text] [-rand files] [-writerand file] [-engine id]

[-provider name] [-provider-path path] [-propquery propq] [-config configfile]

"},{"location":"man1/openssl-genpkey/#description","title":"DESCRIPTION","text":"

This command generates a private key or key pair.

"},{"location":"man1/openssl-genpkey/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-genpkey/#key-generation-options","title":"KEY GENERATION OPTIONS","text":"

The options supported by each algorithm and indeed each implementation of an algorithm can vary. The options for the OpenSSL implementations are detailed below. There are no key generation options defined for the X25519, X448, ED25519 or ED448 algorithms.

"},{"location":"man1/openssl-genpkey/#rsa-key-generation-options","title":"RSA Key Generation Options","text":""},{"location":"man1/openssl-genpkey/#rsa-pss-key-generation-options","title":"RSA-PSS Key Generation Options","text":"

Note: by default an RSA-PSS key has no parameter restrictions.

"},{"location":"man1/openssl-genpkey/#ec-key-generation-options","title":"EC Key Generation Options","text":"

The EC key generation options can also be used for parameter generation.

"},{"location":"man1/openssl-genpkey/#dh-key-generation-options","title":"DH Key Generation Options","text":""},{"location":"man1/openssl-genpkey/#parameter-generation-options","title":"PARAMETER GENERATION OPTIONS","text":"

The options supported by each algorithm and indeed each implementation of an algorithm can vary. The options for the OpenSSL implementations are detailed below.

"},{"location":"man1/openssl-genpkey/#dsa-parameter-generation-options","title":"DSA Parameter Generation Options","text":""},{"location":"man1/openssl-genpkey/#dh-parameter-generation-options","title":"DH Parameter Generation Options","text":"

For most use cases it is recommended to use the group option rather than the type options. Note that the group option is not used by default if no parameter generation options are specified.

"},{"location":"man1/openssl-genpkey/#ec-parameter-generation-options","title":"EC Parameter Generation Options","text":"

The EC parameter generation options are the same as for key generation. See \"EC Key Generation Options\" above.

"},{"location":"man1/openssl-genpkey/#notes","title":"NOTES","text":"

The use of the genpkey program is encouraged over the algorithm specific utilities because additional algorithm options and ENGINE provided algorithms can be used.

"},{"location":"man1/openssl-genpkey/#examples","title":"EXAMPLES","text":"

Generate an RSA private key using default parameters:

openssl genpkey -algorithm RSA -out key.pem\n

Encrypt output private key using 128 bit AES and the passphrase \"hello\":

openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello\n

Generate a 2048 bit RSA key using 3 as the public exponent:

openssl genpkey -algorithm RSA -out key.pem \\\n    -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3\n

Generate 2048 bit DSA parameters that can be validated: The output values for gindex and seed are required for key validation purposes and are not saved to the output pem file).

openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt pbits:2048 \\\n    -pkeyopt qbits:224 -pkeyopt digest:SHA256 -pkeyopt gindex:1 -text\n

Generate DSA key from parameters:

openssl genpkey -paramfile dsap.pem -out dsakey.pem\n

Generate 4096 bit DH Key using safe prime group ffdhe4096:

openssl genpkey -algorithm DH -out dhkey.pem -pkeyopt group:ffdhe4096\n

Generate 2048 bit X9.42 DH key with 256 bit subgroup using RFC5114 group3:

openssl genpkey -algorithm DHX -out dhkey.pem -pkeyopt dh_rfc5114:3\n

Generate a DH key using a DH parameters file:

openssl genpkey -paramfile dhp.pem -out dhkey.pem\n

Output DH parameters for safe prime group ffdhe2048:

openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt group:ffdhe2048\n

Output 2048 bit X9.42 DH parameters with 224 bit subgroup using RFC5114 group2:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -pkeyopt dh_rfc5114:2\n

Output 2048 bit X9.42 DH parameters with 224 bit subgroup using FIP186-4 keygen:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \\\n    -pkeyopt pbits:2048 -pkeyopt qbits:224 -pkeyopt digest:SHA256 \\\n    -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:2\n

Output 1024 bit X9.42 DH parameters with 160 bit subgroup using FIP186-2 keygen:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \\\n    -pkeyopt pbits:1024 -pkeyopt qbits:160 -pkeyopt digest:SHA1 \\\n    -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:1\n

Output 2048 bit DH parameters:

openssl genpkey -genparam -algorithm DH -out dhp.pem \\\n    -pkeyopt dh_paramgen_prime_len:2048\n

Output 2048 bit DH parameters using a generator:

openssl genpkey -genparam -algorithm DH -out dhpx.pem \\\n    -pkeyopt dh_paramgen_prime_len:2048 \\\n    -pkeyopt dh_paramgen_type:1\n

Generate EC parameters:

openssl genpkey -genparam -algorithm EC -out ecp.pem \\\n       -pkeyopt ec_paramgen_curve:secp384r1 \\\n       -pkeyopt ec_param_enc:named_curve\n

Generate EC key from parameters:

openssl genpkey -paramfile ecp.pem -out eckey.pem\n

Generate EC key directly:

openssl genpkey -algorithm EC -out eckey.pem \\\n       -pkeyopt ec_paramgen_curve:P-384 \\\n       -pkeyopt ec_param_enc:named_curve\n

Generate an X25519 private key:

openssl genpkey -algorithm X25519 -out xkey.pem\n

Generate an ED448 private key:

openssl genpkey -algorithm ED448 -out xkey.pem\n
"},{"location":"man1/openssl-genpkey/#history","title":"HISTORY","text":"

The ability to use NIST curve names, and to generate an EC key directly, were added in OpenSSL 1.0.2. The ability to generate X25519 keys was added in OpenSSL 1.1.0. The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-genpkey/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man1/openssl-genrsa/","title":"openssl-genrsa","text":""},{"location":"man1/openssl-genrsa/#name","title":"NAME","text":"

openssl-genrsa - generate an RSA private key

"},{"location":"man1/openssl-genrsa/#synopsis","title":"SYNOPSIS","text":"

openssl genrsa [-help] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-F4] [-f4] [-3] [-primes num] [-verbose] [-quiet] [-traditional] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [numbits]

"},{"location":"man1/openssl-genrsa/#description","title":"DESCRIPTION","text":"

This command generates an RSA private key.

"},{"location":"man1/openssl-genrsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-genrsa/#notes","title":"NOTES","text":"

RSA private key generation essentially involves the generation of two or more prime numbers. When generating a private key various symbols will be output to indicate the progress of the generation. A . represents each number which has passed an initial sieve test, + means a number has passed a single round of the Miller-Rabin primality test, * means the current prime starts a regenerating progress due to some failed tests. A newline means that the number has passed all the prime tests (the actual number depends on the key size).

Because key generation is a random process the time taken to generate a key may vary somewhat. But in general, more primes lead to less generation time of a key.

"},{"location":"man1/openssl-genrsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-gendsa(1)

"},{"location":"man1/openssl-genrsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-info/","title":"openssl-info","text":""},{"location":"man1/openssl-info/#name","title":"NAME","text":"

openssl-info - print OpenSSL built-in information

"},{"location":"man1/openssl-info/#synopsis","title":"SYNOPSIS","text":"

openssl info [-help] [-configdir] [-enginesdir] [-modulesdir ] [-dsoext] [-dirnamesep] [-listsep] [-seeds] [-cpusettings] [-windowscontext]

"},{"location":"man1/openssl-info/#description","title":"DESCRIPTION","text":"

This command is used to print out information about OpenSSL. The information is written exactly as it is with no extra text, which makes useful for scripts.

As a consequence, only one item may be chosen for each run of this command.

"},{"location":"man1/openssl-info/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-info/#history","title":"HISTORY","text":"

This command was added in OpenSSL 3.0.

The -windowscontext option was added in OpenSSL 3.4.

"},{"location":"man1/openssl-info/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-kdf/","title":"openssl-kdf","text":""},{"location":"man1/openssl-kdf/#name","title":"NAME","text":"

openssl-kdf - perform Key Derivation Function operations

"},{"location":"man1/openssl-kdf/#synopsis","title":"SYNOPSIS","text":"

openssl kdf [-help] [-cipher] [-digest] [-mac] [-kdfopt nm:v] [-keylen num] [-out filename] [-binary] [-provider name] [-provider-path path] [-propquery propq] kdf_name

"},{"location":"man1/openssl-kdf/#description","title":"DESCRIPTION","text":"

The key derivation functions generate a derived key from either a secret or password.

"},{"location":"man1/openssl-kdf/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-kdf/#examples","title":"EXAMPLES","text":"

Use TLS1-PRF to create a hex-encoded derived key from a secret key and seed:

openssl kdf -keylen 16 -kdfopt digest:SHA2-256 -kdfopt key:secret \\\n            -kdfopt seed:seed TLS1-PRF\n

Use HKDF to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 10 -kdfopt digest:SHA2-256 -kdfopt key:secret \\\n            -kdfopt salt:salt -kdfopt info:label HKDF\n

Use SSKDF with KMAC to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 64 -kdfopt mac:KMAC-128 -kdfopt maclen:20 \\\n            -kdfopt hexkey:b74a149a161545 -kdfopt hexinfo:348a37a2 \\\n            -kdfopt hexsalt:3638271ccd68a2 SSKDF\n

Use SSKDF with HMAC to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:b74a149a -kdfopt hexinfo:348a37a2 \\\n            -kdfopt hexsalt:3638271c SSKDF\n

Use SSKDF with Hash to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 14 -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:6dbdc23f045488 \\\n            -kdfopt hexinfo:a1b2c3d4 SSKDF\n

Use SSHKDF to create a hex-encoded derived key from a secret key, hash and session_id:

openssl kdf -keylen 16 -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:0102030405 \\\n            -kdfopt hexxcghash:06090A \\\n            -kdfopt hexsession_id:01020304 \\\n            -kdfopt type:A SSHKDF\n

Use PBKDF2 to create a hex-encoded derived key from a password and salt:

openssl kdf -keylen 32 -kdfopt digest:SHA256 -kdfopt pass:password \\\n            -kdfopt salt:salt -kdfopt iter:2 PBKDF2\n

Use scrypt to create a hex-encoded derived key from a password and salt:

openssl kdf -keylen 64 -kdfopt pass:password -kdfopt salt:NaCl \\\n            -kdfopt n:1024 -kdfopt r:8 -kdfopt p:16 \\\n            -kdfopt maxmem_bytes:10485760 SCRYPT\n
"},{"location":"man1/openssl-kdf/#notes","title":"NOTES","text":"

The KDF mechanisms that are available will depend on the options used when building OpenSSL.

"},{"location":"man1/openssl-kdf/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyutl(1), EVP_KDF(3), EVP_KDF-SCRYPT(7), EVP_KDF-TLS1_PRF(7), EVP_KDF-PBKDF2(7), EVP_KDF-HKDF(7), EVP_KDF-SS(7), EVP_KDF-SSHKDF(7), EVP_KDF-X942-ASN1(7), EVP_KDF-X942-CONCAT(7), EVP_KDF-X963(7)

"},{"location":"man1/openssl-kdf/#history","title":"HISTORY","text":"

Added in OpenSSL 3.0

"},{"location":"man1/openssl-kdf/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2023 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.

"},{"location":"man1/openssl-list/","title":"openssl-list","text":""},{"location":"man1/openssl-list/#name","title":"NAME","text":"

openssl-list - list algorithms and features

"},{"location":"man1/openssl-list/#synopsis","title":"SYNOPSIS","text":"

openssl list [-help] [-verbose] [-select name] [-1] [-all-algorithms] [-commands] [-standard-commands] [-digest-algorithms] [-digest-commands] [-kdf-algorithms] [-mac-algorithms] [-random-instances] [-random-generators] [-cipher-algorithms] [-cipher-commands] [-encoders] [-decoders] [-key-managers] [-key-exchange-algorithms] [-kem-algorithms] [-signature-algorithms] [-tls-signature-algorithms] [-asymcipher-algorithms] [-public-key-algorithms] [-public-key-methods] [-store-loaders] [-providers] [-engines] [-disabled] [-objects] [-options command] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-list/#description","title":"DESCRIPTION","text":"

This command is used to generate list of algorithms or disabled features.

"},{"location":"man1/openssl-list/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-list/#display-of-algorithm-names","title":"Display of algorithm names","text":"

Algorithm names may be displayed in one of two manners:

"},{"location":"man1/openssl-list/#history","title":"HISTORY","text":"

The -engines, -digest-commands, and -cipher-commands options were deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-list/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man1/openssl-mac/","title":"openssl-mac","text":""},{"location":"man1/openssl-mac/#name","title":"NAME","text":"

openssl-mac - perform Message Authentication Code operations

"},{"location":"man1/openssl-mac/#synopsis","title":"SYNOPSIS","text":"

openssl mac [-help] [-cipher] [-digest] [-macopt] [-in filename] [-out filename] [-binary] [-provider name] [-provider-path path] [-propquery propq] mac_name

"},{"location":"man1/openssl-mac/#description","title":"DESCRIPTION","text":"

The message authentication code functions output the MAC of a supplied input file.

"},{"location":"man1/openssl-mac/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-mac/#examples","title":"EXAMPLES","text":"

To create a hex-encoded HMAC-SHA1 MAC of a file and write to stdout:

openssl mac -digest SHA1 \\\n        -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \\\n        -in msg.bin HMAC\n

To create a SipHash MAC from a file with a binary file output:

openssl mac -macopt hexkey:000102030405060708090A0B0C0D0E0F \\\n        -in msg.bin -out out.bin -binary SipHash\n

To create a hex-encoded CMAC-AES-128-CBC MAC from a file:

openssl mac -cipher AES-128-CBC \\\n        -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B \\\n        -in msg.bin CMAC\n

To create a hex-encoded KMAC128 MAC from a file with a Customisation String 'Tag' and output length of 16:

openssl mac -macopt custom:Tag -macopt hexkey:40414243444546 \\\n        -macopt size:16 -in msg.bin KMAC128\n

To create a hex-encoded GMAC-AES-128-GCM with a IV from a file:

openssl mac -cipher AES-128-GCM -macopt hexiv:E0E00F19FED7BA0136A797F3 \\\n        -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B -in msg.bin GMAC\n
"},{"location":"man1/openssl-mac/#notes","title":"NOTES","text":"

The MAC mechanisms that are available will depend on the options used when building OpenSSL. Use openssl list -mac-algorithms to list them.

"},{"location":"man1/openssl-mac/#see-also","title":"SEE ALSO","text":"

openssl(1), EVP_MAC(3), EVP_MAC-CMAC(7), EVP_MAC-GMAC(7), EVP_MAC-HMAC(7), EVP_MAC-KMAC(7), EVP_MAC-Siphash(7), EVP_MAC-Poly1305(7)

"},{"location":"man1/openssl-mac/#copyright","title":"COPYRIGHT","text":"

Copyright 2018-2024 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.

"},{"location":"man1/openssl-namedisplay-options/","title":"openssl-namedisplay-options","text":""},{"location":"man1/openssl-namedisplay-options/#name","title":"NAME","text":"

openssl-namedisplay-options - Distinguished name display options

"},{"location":"man1/openssl-namedisplay-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-namedisplay-options/#description","title":"DESCRIPTION","text":"

OpenSSL provides fine-grain control over how the subject and issuer DN's are displayed. This is specified by using the -nameopt option, which takes a comma-separated list of options from the following set. An option may be preceded by a minus sign, -, to turn it off. The default value is utf8,sep_comma_plus_space. The first four are the most commonly used.

"},{"location":"man1/openssl-namedisplay-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-namedisplay-options/#name-format-option-arguments","title":"Name Format Option Arguments","text":"

The DN output format can be fine tuned with the following flags.

"},{"location":"man1/openssl-namedisplay-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-nseq/","title":"openssl-nseq","text":""},{"location":"man1/openssl-nseq/#name","title":"NAME","text":"

openssl-nseq - create or examine a Netscape certificate sequence

"},{"location":"man1/openssl-nseq/#synopsis","title":"SYNOPSIS","text":"

openssl nseq [-help] [-in filename] [-out filename] [-toseq] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-nseq/#description","title":"DESCRIPTION","text":"

This command takes a file containing a Netscape certificate sequence and prints out the certificates contained in it or takes a file of certificates and converts it into a Netscape certificate sequence.

A Netscape certificate sequence is an old Netscape-specific format that can be sometimes be sent to browsers as an alternative to the standard PKCS#7 format when several certificates are sent to the browser, for example during certificate enrollment. It was also used by Netscape certificate server.

"},{"location":"man1/openssl-nseq/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-nseq/#examples","title":"EXAMPLES","text":"

Output the certificates in a Netscape certificate sequence

openssl nseq -in nseq.pem -out certs.pem\n

Create a Netscape certificate sequence

openssl nseq -in certs.pem -toseq -out nseq.pem\n
"},{"location":"man1/openssl-nseq/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-ocsp/","title":"openssl-ocsp","text":""},{"location":"man1/openssl-ocsp/#name","title":"NAME","text":"

openssl-ocsp - Online Certificate Status Protocol command

"},{"location":"man1/openssl-ocsp/#synopsis","title":"SYNOPSIS","text":""},{"location":"man1/openssl-ocsp/#ocsp-client","title":"OCSP Client","text":"

openssl ocsp [-help] [-out file] [-issuer file] [-cert file] [-no_certs] [-serial n] [-signer file] [-signkey file] [-sign_other file] [-nonce] [-no_nonce] [-req_text] [-resp_text] [-text] [-reqout filename] [-respout filename] [-reqin filename] [-respin filename] [-url URL] [-host host:port] [-path pathname] [-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-no_proxy addresses] [-header] [-timeout seconds] [-VAfile file] [-validity_period n] [-status_age n] [-noverify] [-verify_other file] [-trust_other] [-no_intern] [-no_signature_verify] [-no_cert_verify] [-no_chain] [-no_cert_checks] [-no_explicit] [-port num] [-ignore_err]

"},{"location":"man1/openssl-ocsp/#ocsp-server","title":"OCSP Server","text":"

openssl ocsp [-index file] [-CA file] [-rsigner file] [-rkey file] [-passin arg] [-rother file] [-rsigopt nm:v] [-rmd digest] [-badsig] [-resp_no_certs] [-nmin n] [-ndays n] [-resp_key_id] [-nrequest n] [-multi process-count] [-rcid digest] [-digest] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ocsp/#description","title":"DESCRIPTION","text":"

The Online Certificate Status Protocol (OCSP) enables applications to determine the (revocation) state of an identified certificate (RFC 2560).

This command performs many common OCSP tasks. It can be used to print out requests and responses, create requests and send queries to an OCSP responder and behave like a mini OCSP server itself.

"},{"location":"man1/openssl-ocsp/#options","title":"OPTIONS","text":"

This command operates as either a client or a server. The options are described below, divided into those two modes.

"},{"location":"man1/openssl-ocsp/#ocsp-client-options","title":"OCSP Client Options","text":""},{"location":"man1/openssl-ocsp/#ocsp-server-options","title":"OCSP Server Options","text":""},{"location":"man1/openssl-ocsp/#ocsp-response-verification","title":"OCSP RESPONSE VERIFICATION","text":"

OCSP Response follows the rules specified in RFC2560.

Initially the OCSP responder certificate is located and the signature on the OCSP request checked using the responder certificate's public key.

Then a normal certificate verify is performed on the OCSP responder certificate building up a certificate chain in the process. The locations of the trusted certificates used to build the chain can be specified by the -CAfile, -CApath or -CAstore options or they will be looked for in the standard OpenSSL certificates directory.

If the initial verify fails then the OCSP verify process halts with an error.

Otherwise the issuing CA certificate in the request is compared to the OCSP responder certificate: if there is a match then the OCSP verify succeeds.

Otherwise the OCSP responder certificate's CA is checked against the issuing CA certificate in the request. If there is a match and the OCSPSigning extended key usage is present in the OCSP responder certificate then the OCSP verify succeeds.

Otherwise, if -no_explicit is not set the root CA of the OCSP responders CA is checked to see if it is trusted for OCSP signing. If it is the OCSP verify succeeds.

If none of these checks is successful then the OCSP verify fails.

What this effectively means if that if the OCSP responder certificate is authorised directly by the CA it is issuing revocation information about (and it is correctly configured) then verification will succeed.

If the OCSP responder is a \"global responder\" which can give details about multiple CAs and has its own separate certificate chain then its root CA can be trusted for OCSP signing. For example:

openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem\n

Alternatively the responder certificate itself can be explicitly trusted with the -VAfile option.

"},{"location":"man1/openssl-ocsp/#notes","title":"NOTES","text":"

As noted, most of the verify options are for testing or debugging purposes. Normally only the -CApath, -CAfile, -CAstore and (if the responder is a 'global VA') -VAfile options need to be used.

The OCSP server is only useful for test and demonstration purposes: it is not really usable as a full OCSP responder. It contains only a very simple HTTP request handling and can only handle the POST form of OCSP queries. It also handles requests serially meaning it cannot respond to new requests until it has processed the current one. The text index file format of revocation is also inefficient for large quantities of revocation data.

It is possible to run this command in responder mode via a CGI script using the -reqin and -respout options.

"},{"location":"man1/openssl-ocsp/#examples","title":"EXAMPLES","text":"

Create an OCSP request and write it to a file:

openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der\n

Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the response to a file, print it out in text form, and verify the response:

openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \\\n    -url http://ocsp.myhost.com/ -resp_text -respout resp.der\n

Read in an OCSP response and print out text form:

openssl ocsp -respin resp.der -text -noverify\n

OCSP server on port 8888 using a standard ca configuration, and a separate responder certificate. All requests and responses are printed to a file.

openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem\n       -text -out log.txt\n

As above but exit after processing one request:

openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem\n    -nrequest 1\n

Query status information using an internally generated request:

openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem\n    -issuer demoCA/cacert.pem -serial 1\n

Query status information using request read from a file, and write the response to a second file.

openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem\n    -reqin req.der -respout resp.der\n
"},{"location":"man1/openssl-ocsp/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0.

"},{"location":"man1/openssl-ocsp/#copyright","title":"COPYRIGHT","text":"

Copyright 2001-2023 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.

"},{"location":"man1/openssl-passphrase-options/","title":"openssl-passphrase-options","text":""},{"location":"man1/openssl-passphrase-options/#name","title":"NAME","text":"

openssl-passphrase-options - Pass phrase options

"},{"location":"man1/openssl-passphrase-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-passphrase-options/#description","title":"DESCRIPTION","text":"

Several OpenSSL commands accept password arguments, typically using -passin and -passout for input and output passwords respectively. These allow the password to be obtained from a variety of sources. Both of these options take a single argument whose format is described below. If no password argument is given and a password is required then the user is prompted to enter one: this will typically be read from the current terminal with echoing turned off.

Note that character encoding may be relevant, please see passphrase-encoding(7).

"},{"location":"man1/openssl-passphrase-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-passphrase-options/#pass-phrase-option-arguments","title":"Pass Phrase Option Arguments","text":"

Pass phrase arguments can be formatted as follows.

"},{"location":"man1/openssl-passphrase-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-passwd/","title":"openssl-passwd","text":""},{"location":"man1/openssl-passwd/#name","title":"NAME","text":"

openssl-passwd - compute password hashes

"},{"location":"man1/openssl-passwd/#synopsis","title":"SYNOPSIS","text":"

openssl passwd [-help] [-1] [-apr1] [-aixmd5] [-5] [-6] [-salt string] [-in file] [-stdin] [-noverify] [-quiet] [-table] [-reverse] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [password]

"},{"location":"man1/openssl-passwd/#description","title":"DESCRIPTION","text":"

This command computes the hash of a password typed at run-time or the hash of each password in a list. The password list is taken from the named file for option -in, from stdin for option -stdin, or from the command line, or from the terminal otherwise.

"},{"location":"man1/openssl-passwd/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-passwd/#examples","title":"EXAMPLES","text":"
% openssl passwd -1 -salt xxxxxxxx password\n$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.\n\n% openssl passwd -apr1 -salt xxxxxxxx password\n$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0\n\n% openssl passwd -aixmd5 -salt xxxxxxxx password\nxxxxxxxx$8Oaipk/GPKhC64w/YVeFD/\n
"},{"location":"man1/openssl-passwd/#history","title":"HISTORY","text":"

The -crypt option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-passwd/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-pkcs12/","title":"openssl-pkcs12","text":""},{"location":"man1/openssl-pkcs12/#name","title":"NAME","text":"

openssl-pkcs12 - PKCS#12 file command

"},{"location":"man1/openssl-pkcs12/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs12 [-help] [-passin arg] [-passout arg] [-password arg] [-twopass] [-in filename|uri] [-out filename] [-nokeys] [-nocerts] [-noout] [-legacy] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-rand files] [-writerand file]

PKCS#12 input (parsing) options: [-info] [-nomacver] [-clcerts] [-cacerts]

[-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-noenc] [-nodes]

PKCS#12 output (export) options:

[-export] [-inkey filename|uri] [-certfile filename] [-passcerts arg] [-chain] [-untrusted filename] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-name name] [-caname name] [-CSP name] [-LMK] [-keyex] [-keysig] [-keypbe cipher] [-certpbe cipher] [-descert] [-macalg digest] [-pbmac1_pbkdf2] [-pbmac1_pbkdf2_md digest] [-iter count] [-noiter] [-nomaciter] [-maciter] [-macsaltlen] [-nomac] [-jdktrust usage]

"},{"location":"man1/openssl-pkcs12/#description","title":"DESCRIPTION","text":"

This command allows PKCS#12 files (sometimes referred to as PFX files) to be created and parsed. PKCS#12 files are used by several programs including Netscape, MSIE and MS Outlook.

"},{"location":"man1/openssl-pkcs12/#options","title":"OPTIONS","text":"

There are a lot of options the meaning of some depends of whether a PKCS#12 file is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 file can be created by using the -export option (see below). The PKCS#12 export encryption and MAC options such as -certpbe and -iter and many further options such as -chain are relevant only with -export. Conversely, the options regarding encryption of private keys when outputting PKCS#12 input are relevant only when the -export option is not given.

The default encryption algorithm is AES-256-CBC with PBKDF2 for key derivation.

When encountering problems loading legacy PKCS#12 files that involve, for example, RC2-40-CBC, try using the -legacy option and, if needed, the -provider-path option.

"},{"location":"man1/openssl-pkcs12/#pkcs12-input-parsing-options","title":"PKCS#12 input (parsing) options","text":""},{"location":"man1/openssl-pkcs12/#pkcs12-output-export-options","title":"PKCS#12 output (export) options","text":""},{"location":"man1/openssl-pkcs12/#notes","title":"NOTES","text":"

Although there are a large number of options most of them are very rarely used. For PKCS#12 file parsing only -in and -out need to be used for PKCS#12 file creation -export and -name are also used.

If none of the -clcerts, -cacerts or -nocerts options are present then all certificates will be output in the order they appear in the input PKCS#12 files. There is no guarantee that the first certificate present is the one corresponding to the private key. Certain software which tries to get a private key and the corresponding certificate might assume that the first certificate in the file is the one corresponding to the private key, but that may not always be the case. Using the -clcerts option will solve this problem by only outputting the certificate corresponding to the private key. If the CA certificates are required then they can be output to a separate file using the -nokeys -cacerts options to just output CA certificates.

The -keypbe and -certpbe algorithms allow the precise encryption algorithms for private keys and certificates to be specified. Normally the defaults are fine but occasionally software can't handle triple DES encrypted private keys, then the option -keypbe PBE-SHA1-RC2-40 can be used to reduce the private key encryption to 40 bit RC2. A complete description of all algorithms is contained in openssl-pkcs8(1).

Prior 1.1 release passwords containing non-ASCII characters were encoded in non-compliant manner, which limited interoperability, in first hand with Windows. But switching to standard-compliant password encoding poses problem accessing old data protected with broken encoding. For this reason even legacy encodings is attempted when reading the data. If you use PKCS#12 files in production application you are advised to convert the data, because implemented heuristic approach is not MT-safe, its sole goal is to facilitate the data upgrade with this command.

"},{"location":"man1/openssl-pkcs12/#examples","title":"EXAMPLES","text":"

Parse a PKCS#12 file and output it to a PEM file:

openssl pkcs12 -in file.p12 -out file.pem\n

Output only client certificates to a file:

openssl pkcs12 -in file.p12 -clcerts -out file.pem\n

Don't encrypt the private key:

openssl pkcs12 -in file.p12 -out file.pem -noenc\n

Print some info about a PKCS#12 file:

openssl pkcs12 -in file.p12 -info -noout\n

Print some info about a PKCS#12 file in legacy mode:

openssl pkcs12 -in file.p12 -info -noout -legacy\n

Create a PKCS#12 file from a PEM file that may contain a key and certificates:

openssl pkcs12 -export -in file.pem -out file.p12 -name \"My PSE\"\n

Include some extra certificates:

openssl pkcs12 -export -in file.pem -out file.p12 -name \"My PSE\" \\\n -certfile othercerts.pem\n

Export a PKCS#12 file with data from a certificate PEM file and from a further PEM file containing a key, with default algorithms as in the legacy provider:

openssl pkcs12 -export -in cert.pem -inkey key.pem -out file.p12 -legacy\n
"},{"location":"man1/openssl-pkcs12/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkcs8(1), ossl_store-file(7)

"},{"location":"man1/openssl-pkcs12/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0. The -nodes option was deprecated in OpenSSL 3.0, too; use -noenc instead.

"},{"location":"man1/openssl-pkcs12/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-pkcs7/","title":"openssl-pkcs7","text":""},{"location":"man1/openssl-pkcs7/#name","title":"NAME","text":"

openssl-pkcs7 - PKCS#7 command

"},{"location":"man1/openssl-pkcs7/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs7 [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-print] [-print_certs] [-quiet] [-text] [-noout] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkcs7/#description","title":"DESCRIPTION","text":"

This command processes PKCS#7 files. Note that it only understands PKCS#7 v 1.5 as specified in IETF RFC 2315. It cannot currently parse CMS as described in IETF RFC 2630.

"},{"location":"man1/openssl-pkcs7/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkcs7/#examples","title":"EXAMPLES","text":"

Convert a PKCS#7 file from PEM to DER:

openssl pkcs7 -in file.pem -outform DER -out file.der\n

Output all certificates in a file:

openssl pkcs7 -in file.pem -print_certs -out certs.pem\n
"},{"location":"man1/openssl-pkcs7/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl2pkcs7(1)

"},{"location":"man1/openssl-pkcs7/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkcs7/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man1/openssl-pkcs8/","title":"openssl-pkcs8","text":""},{"location":"man1/openssl-pkcs8/#name","title":"NAME","text":"

openssl-pkcs8 - PKCS#8 format private key conversion command

"},{"location":"man1/openssl-pkcs8/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs8 [-help] [-topk8] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-iter count] [-noiter] [-nocrypt] [-traditional] [-v2 alg] [-v2prf alg] [-v1 alg] [-scrypt] [-scrypt_N N] [-scrypt_r r] [-scrypt_p p] [-saltlen size] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkcs8/#description","title":"DESCRIPTION","text":"

This command processes private keys in PKCS#8 format. It can handle both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.

"},{"location":"man1/openssl-pkcs8/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkcs8/#notes","title":"NOTES","text":"

By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit AES with HMAC and SHA256 is used.

Some older implementations do not support PKCS#5 v2.0 format and require the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak encryption algorithms such as 56 bit DES.

Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration counts are more secure that those encrypted using the traditional SSLeay compatible formats. So if additional security is considered important the keys should be converted.

It is possible to write out DER encoded encrypted private keys in PKCS#8 format because the encryption details are included at an ASN1 level whereas the traditional format includes them at a PEM level.

"},{"location":"man1/openssl-pkcs8/#pkcs5-v15-and-pkcs12-algorithms","title":"PKCS#5 V1.5 AND PKCS#12 ALGORITHMS","text":"

Various algorithms can be used with the -v1 command line option, including PKCS#5 v1.5 and PKCS#12. These are described in more detail below.

"},{"location":"man1/openssl-pkcs8/#examples","title":"EXAMPLES","text":"

Convert a private key to PKCS#8 format using default parameters (AES with 256 bit key and hmacWithSHA256):

openssl pkcs8 -in key.pem -topk8 -out enckey.pem\n

Convert a private key to PKCS#8 unencrypted format:

openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem\n

Convert a private key to PKCS#5 v2.0 format using triple DES:

openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem\n

Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC mode and hmacWithSHA512 PRF:

openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem\n

Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm (DES):

openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem\n

Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm (3DES):

openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES\n

Read a DER unencrypted PKCS#8 format private key:

openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem\n

Convert a private key from any PKCS#8 encrypted format to traditional format:

openssl pkcs8 -in pk8.pem -traditional -out key.pem\n

Convert a private key to PKCS#8 format, encrypting with AES-256 and with one million iterations of the password:

openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem\n
"},{"location":"man1/openssl-pkcs8/#standards","title":"STANDARDS","text":"

Test vectors from this PKCS#5 v2.0 implementation were posted to the pkcs-tng mailing list using triple DES, DES and RC2 with high iteration counts, several people confirmed that they could decrypt the private keys produced and therefore, it can be assumed that the PKCS#5 v2.0 implementation is reasonably accurate at least as far as these algorithms are concerned.

The format of PKCS#8 DSA (and other) private keys is not well documented: it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA PKCS#8 private key format complies with this standard.

"},{"location":"man1/openssl-pkcs8/#bugs","title":"BUGS","text":"

There should be an option that prints out the encryption algorithm in use and other details such as the iteration count.

"},{"location":"man1/openssl-pkcs8/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-dsa(1), openssl-rsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkcs8/#history","title":"HISTORY","text":"

The -iter option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkcs8/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-pkey/","title":"openssl-pkey","text":""},{"location":"man1/openssl-pkey/#name","title":"NAME","text":"

openssl-pkey - public or private key processing command

"},{"location":"man1/openssl-pkey/#synopsis","title":"SYNOPSIS","text":"

openssl pkey [-help] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-check] [-pubcheck] [-in filename|uri] [-inform DER|PEM|P12|ENGINE] [-passin arg] [-pubin] [-out filename] [-outform DER|PEM] [-cipher] [-passout arg] [-traditional] [-pubout] [-noout] [-text] [-text_pub] [-ec_conv_form arg] [-ec_param_enc arg]

"},{"location":"man1/openssl-pkey/#description","title":"DESCRIPTION","text":"

This command processes public or private keys. They can be converted between various forms and their components printed.

"},{"location":"man1/openssl-pkey/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkey/#general-options","title":"General options","text":""},{"location":"man1/openssl-pkey/#input-options","title":"Input options","text":""},{"location":"man1/openssl-pkey/#output-options","title":"Output options","text":""},{"location":"man1/openssl-pkey/#examples","title":"EXAMPLES","text":"

To remove the pass phrase on a private key:

openssl pkey -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl pkey -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl pkey -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl pkey -in key.pem -text -noout\n

To print out the public components of a private key to standard output:

openssl pkey -in key.pem -text_pub -noout\n

To just output the public part of a private key:

openssl pkey -in key.pem -pubout -out pubkey.pem\n

To change the EC parameters encoding to explicit:

openssl pkey -in key.pem -ec_param_enc explicit -out keyout.pem\n

To change the EC point conversion form to compressed:

openssl pkey -in key.pem -ec_conv_form compressed -out keyout.pem\n
"},{"location":"man1/openssl-pkey/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-rsa(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkey/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkey/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2023 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.

"},{"location":"man1/openssl-pkeyparam/","title":"openssl-pkeyparam","text":""},{"location":"man1/openssl-pkeyparam/#name","title":"NAME","text":"

openssl-pkeyparam - public key algorithm parameter processing command

"},{"location":"man1/openssl-pkeyparam/#synopsis","title":"SYNOPSIS","text":"

openssl pkeyparam [-help] [-in filename] [-out filename] [-text] [-noout] [-check] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkeyparam/#description","title":"DESCRIPTION","text":"

This command processes public key algorithm parameters. They can be checked for correctness and their components printed out.

"},{"location":"man1/openssl-pkeyparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkeyparam/#examples","title":"EXAMPLES","text":"

Print out text version of parameters:

openssl pkeyparam -in param.pem -text\n
"},{"location":"man1/openssl-pkeyparam/#notes","title":"NOTES","text":"

There are no -inform or -outform options for this command because only PEM format is supported because the key type is determined by the PEM headers.

"},{"location":"man1/openssl-pkeyparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-rsa(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkeyparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkeyparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man1/openssl-pkeyutl/","title":"openssl-pkeyutl","text":""},{"location":"man1/openssl-pkeyutl/#name","title":"NAME","text":"

openssl-pkeyutl - public key algorithm command

"},{"location":"man1/openssl-pkeyutl/#synopsis","title":"SYNOPSIS","text":"

openssl pkeyutl [-help] [-in file] [-rawin] [-digest algorithm] [-out file] [-secret file] [-sigfile file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-peerkey file] [-peerform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-encap] [-decap] [-kdf algorithm] [-kdflen length] [-kemop operation] [-pkeyopt opt:value] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile]

"},{"location":"man1/openssl-pkeyutl/#description","title":"DESCRIPTION","text":"

This command can be used to perform low-level public key operations using any supported algorithm.

"},{"location":"man1/openssl-pkeyutl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkeyutl/#notes","title":"NOTES","text":"

The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below.

Unless otherwise mentioned all algorithms support the digest:alg option which specifies the digest in use for sign, verify and verifyrecover operations. The value alg should represent a digest name as used in the EVP_get_digestbyname() function for example sha1. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the lengths of data passed in and for creating the structures that make up the signature (e.g. DigestInfo in RSASSA PKCS#1 v1.5 signatures).

This command does not hash the input data (except where -rawin is used) but rather it will use the data directly as input to the signature algorithm. Depending on the key type, signature type, and mode of padding, the maximum acceptable lengths of input data differ. The signed data can't be longer than the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer than the field size, otherwise it will be silently truncated to the field size. In any event the input size must not be larger than the largest supported digest size.

In other words, if the value of digest is sha1 the input should be the 20 bytes long binary encoding of the SHA-1 hash function output.

"},{"location":"man1/openssl-pkeyutl/#rsa-algorithm","title":"RSA ALGORITHM","text":"

The RSA algorithm generally supports the encrypt, decrypt, sign, verify and verifyrecover operations. However, some padding modes support only a subset of these operations. The following additional pkeyopt values are supported:

"},{"location":"man1/openssl-pkeyutl/#rsa-pss-algorithm","title":"RSA-PSS ALGORITHM","text":"

The RSA-PSS algorithm is a restricted version of the RSA algorithm which only supports the sign and verify operations with PSS padding. The following additional -pkeyopt values are supported:

"},{"location":"man1/openssl-pkeyutl/#dsa-algorithm","title":"DSA ALGORITHM","text":"

The DSA algorithm supports signing and verification operations only. Currently there are no additional -pkeyopt options other than digest. The SHA1 digest is assumed by default.

"},{"location":"man1/openssl-pkeyutl/#dh-algorithm","title":"DH ALGORITHM","text":"

The DH algorithm only supports the derivation operation and no additional -pkeyopt options.

"},{"location":"man1/openssl-pkeyutl/#ec-algorithm","title":"EC ALGORITHM","text":"

The EC algorithm supports sign, verify and derive operations. The sign and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for the -pkeyopt digest option.

"},{"location":"man1/openssl-pkeyutl/#x25519-and-x448-algorithms","title":"X25519 AND X448 ALGORITHMS","text":"

The X25519 and X448 algorithms support key derivation only. Currently there are no additional options.

"},{"location":"man1/openssl-pkeyutl/#ed25519-and-ed448-algorithms","title":"ED25519 AND ED448 ALGORITHMS","text":"

These algorithms only support signing and verifying. OpenSSL only implements the \"pure\" variants of these algorithms so raw data can be passed directly to them without hashing them first. The option -rawin must be used with these algorithms with no -digest specified. Additionally OpenSSL only supports \"oneshot\" operation with these algorithms. This means that the entire file to be signed/verified must be read into memory before processing it. Signing or Verifying very large files should be avoided. Additionally the size of the file must be known for this to work. If the size of the file cannot be determined (for example if the input is stdin) then the sign or verify operation will fail.

"},{"location":"man1/openssl-pkeyutl/#sm2","title":"SM2","text":"

The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For the sign and verify operations, SM2 requires an Distinguishing ID string to be passed in. The following -pkeyopt value is supported:

"},{"location":"man1/openssl-pkeyutl/#examples","title":"EXAMPLES","text":"

Sign some data using a private key:

openssl pkeyutl -sign -in file -inkey key.pem -out sig\n

Recover the signed data (e.g. if an RSA key is used):

openssl pkeyutl -verifyrecover -in sig -inkey key.pem\n

Verify the signature (e.g. a DSA key):

openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem\n

Sign data using a message digest value (this is currently only valid for RSA):

openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256\n

Derive a shared secret value:

openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret\n

Hexdump 48 bytes of TLS1 PRF using digest SHA256 and shared secret and seed consisting of the single byte 0xFF:

openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \\\n   -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump\n

Derive a key using scrypt where the password is read from command line:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \\\n   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1\n

Derive using the same algorithm, but read key from environment variable MYPASS:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \\\n   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1\n

Sign some data using an SM2(7) private key and a specific ID:

openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \\\n   -pkeyopt distid:someid\n

Verify some data using an SM2(7) certificate and a specific ID:

openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \\\n   -rawin -digest sm3 -pkeyopt distid:someid\n

Decrypt some data using a private key with OAEP padding using SHA256:

openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \\\n   -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256\n
"},{"location":"man1/openssl-pkeyutl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-pkey(1), openssl-rsautl(1) openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1), openssl-kdf(1) EVP_PKEY_CTX_set_hkdf_md(3), EVP_PKEY_CTX_set_tls1_prf_md(3),

"},{"location":"man1/openssl-pkeyutl/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkeyutl/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man1/openssl-prime/","title":"openssl-prime","text":""},{"location":"man1/openssl-prime/#name","title":"NAME","text":"

openssl-prime - compute prime numbers

"},{"location":"man1/openssl-prime/#synopsis","title":"SYNOPSIS","text":"

openssl prime [-help] [-hex] [-generate] [-bits num] [-safe] [-provider name] [-provider-path path] [-propquery propq] [-checks num] [number ...]

"},{"location":"man1/openssl-prime/#description","title":"DESCRIPTION","text":"

This command checks if the specified numbers are prime.

If no numbers are given on the command line, the -generate flag should be used to generate primes according to the requirements specified by the rest of the flags.

"},{"location":"man1/openssl-prime/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-prime/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-rand/","title":"openssl-rand","text":""},{"location":"man1/openssl-rand/#name","title":"NAME","text":"

openssl-rand - generate pseudo-random bytes

"},{"location":"man1/openssl-rand/#synopsis","title":"SYNOPSIS","text":"

openssl rand [-help] [-out file] [-base64] [-hex] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] num[K|M|G|T]

"},{"location":"man1/openssl-rand/#description","title":"DESCRIPTION","text":"

This command generates num random bytes using a cryptographically secure pseudo random number generator (CSPRNG). A suffix [K|M|G|T] may be appended to the num value to indicate the requested value be scaled as a multiple of KiB/MiB/GiB/TiB respectively. Note that suffixes are case sensitive, and that the suffixes represent binary multiples (K = 1024 bytes, M = 1024*1024 bytes, etc).

The string 'max' may be substituted for a numerical value in num, to request the maximum number of bytes the CSPRNG can produce per instantiation. Currently, this is restricted to 2^61 bytes as per NIST SP 800-90C.

The random bytes are generated using the RAND_bytes(3) function, which provides a security level of 256 bits, provided it managed to seed itself successfully from a trusted operating system entropy source. Otherwise, the command will fail with a nonzero error code. For more details, see RAND_bytes(3), RAND(7), and EVP_RAND(7).

"},{"location":"man1/openssl-rand/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rand/#see-also","title":"SEE ALSO","text":"

openssl(1), RAND_bytes(3), RAND(7), EVP_RAND(7)

"},{"location":"man1/openssl-rand/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rand/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-rehash/","title":"openssl-rehash","text":""},{"location":"man1/openssl-rehash/#name","title":"NAME","text":"

openssl-rehash, c_rehash - Create symbolic links to files named by the hash values

"},{"location":"man1/openssl-rehash/#synopsis","title":"SYNOPSIS","text":"

openssl rehash [-h] [-help] [-old] [-compat] [-n] [-v] [-provider name] [-provider-path path] [-propquery propq] [directory] ...

c_rehash [-h] [-help] [-old] [-n] [-v] [-provider name] [-provider-path path] [-propquery propq] [directory] ...

"},{"location":"man1/openssl-rehash/#description","title":"DESCRIPTION","text":"

This command is generally equivalent to the external script c_rehash, except for minor differences noted below.

openssl rehash scans directories and calculates a hash value of each .pem, .crt, .cer, or .crl file in the specified directory list and creates symbolic links for each file, where the name of the link is the hash value. (If the platform does not support symbolic links, a copy is made.) This command is useful as many programs that use OpenSSL require directories to be set up like this in order to find certificates.

If any directories are named on the command line, then those are processed in turn. If not, then the SSL_CERT_DIR environment variable is consulted; this should be a colon-separated list of directories, like the Unix PATH variable. If that is not set then the default directory (installation-specific but often /usr/local/ssl/certs) is processed.

In order for a directory to be processed, the user must have write permissions on that directory, otherwise an error will be generated.

The links created are of the form HHHHHHHH.D, where each H is a hexadecimal character and D is a single decimal digit. When a directory is processed, all links in it that have a name in that syntax are first removed, even if they are being used for some other purpose. To skip the removal step, use the -n flag. Hashes for CRL's look similar except the letter r appears after the period, like this: HHHHHHHH.rD.

Multiple objects may have the same hash; they will be indicated by incrementing the D value. Duplicates are found by comparing the full SHA-1 fingerprint. A warning will be displayed if a duplicate is found.

A warning will also be displayed if there are files that cannot be parsed as either a certificate or a CRL or if more than one such object appears in the file.

"},{"location":"man1/openssl-rehash/#script-configuration","title":"Script Configuration","text":"

The c_rehash script uses the openssl program to compute the hashes and fingerprints. If not found in the user's PATH, then set the OPENSSL environment variable to the full pathname. Any program can be used, it will be invoked as follows for either a certificate or CRL:

$OPENSSL x509 -hash -fingerprint -noout -in FILENAME\n$OPENSSL crl -hash -fingerprint -noout -in FILENAME\n

where FILENAME is the filename. It must output the hash of the file on the first line, and the fingerprint on the second, optionally prefixed with some text and an equals sign.

"},{"location":"man1/openssl-rehash/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rehash/#environment","title":"ENVIRONMENT","text":""},{"location":"man1/openssl-rehash/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl(1), openssl-x509(1)

"},{"location":"man1/openssl-rehash/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-req/","title":"openssl-req","text":""},{"location":"man1/openssl-req/#name","title":"NAME","text":"

openssl-req - PKCS#10 certificate request and certificate generating command

"},{"location":"man1/openssl-req/#synopsis","title":"SYNOPSIS","text":"

openssl req [-help] [-cipher] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-text] [-pubkey] [-noout] [-verify] [-modulus] [-new] [-newkey arg] [-pkeyopt opt:value] [-noenc] [-nodes] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-keyout filename] [-keygen_engine id] [-digest] [-config filename] [-section name] [-x509] [-x509v1] [-CA filename|uri] [-CAkey filename|uri] [-not_before date] [-not_after date] [-days n] [-set_serial n] [-newhdr] [-copy_extensions arg] [-extensions section] [-reqexts section] [-addext ext] [-precert] [-utf8] [-reqopt] [-subject] [-subj arg] [-multivalue-rdn] [-sigopt nm:v] [-vfyopt nm:v] [-batch] [-verbose] [-quiet] [-nameopt option] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-req/#description","title":"DESCRIPTION","text":"

This command primarily creates and processes certificate requests (CSRs) in PKCS#10 format. It can additionally create self-signed certificates for use as root CAs for example.

"},{"location":"man1/openssl-req/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-req/#configuration-file-format","title":"CONFIGURATION FILE FORMAT","text":"

The configuration options are specified in the req section of the configuration file. An alternate name be specified by using the -section option. As with all configuration files, if no value is specified in the specific section then the initial unnamed or default section is searched too.

The options available are described in detail below.

"},{"location":"man1/openssl-req/#distinguished-name-and-attribute-section-format","title":"DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT","text":"

There are two separate formats for the distinguished name and attribute sections. If the prompt option is set to no then these sections just consist of field names and values: for example,

CN=My Name\nOU=My Organization\nemailAddress=someone@somewhere.org\n

This allows external programs (e.g. GUI based) to generate a template file with all the field names and values and just pass it to this command. An example of this kind of configuration file is contained in the EXAMPLES section.

Alternatively if the prompt option is absent or not set to no then the file contains field prompting information. It consists of lines of the form:

fieldName=\"prompt\"\nfieldName_default=\"default field value\"\nfieldName_min= 2\nfieldName_max= 4\n

\"fieldName\" is the field name being used, for example commonName (or CN). The \"prompt\" string is used to ask the user to enter the relevant details. If the user enters nothing then the default value is used if no default value is present then the field is omitted. A field can still be omitted if a default value is present if the user just enters the '.' character.

The number of characters entered must be between the fieldName_min and fieldName_max limits: there may be additional restrictions based on the field being used (for example countryName can only ever be two characters long and must fit in a PrintableString).

Some fields (such as organizationName) can be used more than once in a DN. This presents a problem because configuration files will not recognize the same name occurring twice. To avoid this problem if the fieldName contains some characters followed by a full stop they will be ignored. So for example a second organizationName can be input by calling it \"1.organizationName\".

The actual permitted field names are any object identifier short or long names. These are compiled into OpenSSL and include the usual values such as commonName, countryName, localityName, organizationName, organizationalUnitName, stateOrProvinceName. Additionally emailAddress is included as well as name, surname, givenName, initials, and dnQualifier.

Additional object identifiers can be defined with the oid_file or oid_section options in the configuration file. Any additional fields will be treated as though they were a DirectoryString.

"},{"location":"man1/openssl-req/#examples","title":"EXAMPLES","text":"

Examine and verify certificate request:

openssl req -in req.pem -text -verify -noout\n

Specify the cipher to be used for encrypting the private key:

openssl req -newkey rsa:2048 -keyout privatekey.pem -out request.csr -cipher aes-256-cbc\n

Create a private key and then generate a certificate request from it:

openssl genrsa -out key.pem 2048\nopenssl req -new -key key.pem -out req.pem\n

The same but just using req:

openssl req -newkey rsa:2048 -keyout key.pem -out req.pem\n

Generate a self-signed root certificate:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem\n

Create an SM2 private key and then generate a certificate request from it:

openssl ecparam -genkey -name SM2 -out sm2.key\nopenssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt \"distid:1234567812345678\"\n

Examine and verify an SM2 certificate request:

openssl req -verify -in sm2.csr -sm3 -vfyopt \"distid:1234567812345678\"\n

Example of a file pointed to by the oid_file option:

1.2.3.4        shortName       A longer Name\n1.2.3.6        otherName       Other longer Name\n

Example of a section pointed to by oid_section making use of variable expansion:

testoid1=1.2.3.5\ntestoid2=${testoid1}.6\n

Sample configuration file prompting for field values:

[ req ]\ndefault_bits           = 2048\ndefault_keyfile        = privkey.pem\ndistinguished_name     = req_distinguished_name\nattributes             = req_attributes\nreq_extensions         = v3_ca\n\ndirstring_type = nobmp\n\n[ req_distinguished_name ]\ncountryName                    = Country Name (2 letter code)\ncountryName_default            = AU\ncountryName_min                = 2\ncountryName_max                = 2\n\nlocalityName                   = Locality Name (eg, city)\n\norganizationalUnitName         = Organizational Unit Name (eg, section)\n\ncommonName                     = Common Name (eg, YOUR name)\ncommonName_max                 = 64\n\nemailAddress                   = Email Address\nemailAddress_max               = 40\n\n[ req_attributes ]\nchallengePassword              = A challenge password\nchallengePassword_min          = 4\nchallengePassword_max          = 20\n\n[ v3_ca ]\n\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid:always,issuer:always\nbasicConstraints = critical, CA:true\n

Sample configuration containing all field values:

[ req ]\ndefault_bits           = 2048\ndefault_keyfile        = keyfile.pem\ndistinguished_name     = req_distinguished_name\nattributes             = req_attributes\nprompt                 = no\noutput_password        = mypass\n\n[ req_distinguished_name ]\nC                      = GB\nST                     = Test State or Province\nL                      = Test Locality\nO                      = Organization Name\nOU                     = Organizational Unit Name\nCN                     = Common Name\nemailAddress           = test@email.address\n\n[ req_attributes ]\nchallengePassword              = A challenge password\n

Example of giving the most common attributes (subject and extensions) on the command line:

openssl req -new -subj \"/C=GB/CN=foo\" \\\n                 -addext \"subjectAltName = DNS:foo.co.uk\" \\\n                 -addext \"certificatePolicies = 1.2.3.4\" \\\n                 -newkey rsa:2048 -keyout key.pem -out req.pem\n
"},{"location":"man1/openssl-req/#notes","title":"NOTES","text":"

The certificate requests generated by Xenroll with MSIE have extensions added. It includes the keyUsage extension which determines the type of key (signature only or general purpose) and any additional OIDs entered by the script in an extendedKeyUsage extension.

"},{"location":"man1/openssl-req/#diagnostics","title":"DIAGNOSTICS","text":"

The following messages are frequently asked about:

    Using configuration from /some/path/openssl.cnf\n    Unable to load config info\n

This is followed some time later by:

    unable to find 'distinguished_name' in config\n    problems making Certificate Request\n

The first error message is the clue: it can't find the configuration file! Certain operations (like examining a certificate request) don't need a configuration file so its use isn't enforced. Generation of certificates or requests however does need a configuration file. This could be regarded as a bug.

Another puzzling message is this:

    Attributes:\n        a0:00\n

this is displayed when no attributes are present and the request includes the correct empty SET OF structure (the DER encoding of which is 0xa0 0x00). If you just see:

    Attributes:\n

then the SET OF is missing and the encoding is technically invalid (but it is tolerated). See the description of the command line option -asn1-kludge for more information.

"},{"location":"man1/openssl-req/#bugs","title":"BUGS","text":"

OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. This can cause problems if you need characters that aren't available in PrintableStrings and you don't want to or can't use BMPStrings.

As a consequence of the T61String handling the only correct way to represent accented characters in OpenSSL is to use a BMPString: unfortunately Netscape currently chokes on these. If you have to use accented characters with Netscape and MSIE then you currently need to use the invalid T61String form.

The current prompting is not very friendly. It doesn't allow you to confirm what you've just entered. Other things like extensions in certificate requests are statically defined in the configuration file. Some of these: like an email address in subjectAltName should be input by the user.

"},{"location":"man1/openssl-req/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-x509(1), openssl-ca(1), openssl-genrsa(1), openssl-gendsa(1), config(5), x509v3_config(5)

"},{"location":"man1/openssl-req/#history","title":"HISTORY","text":"

The default encryption cipher was changed from 3DES to AES-256 in OpenSSL 3.5.

The -section option was added in OpenSSL 3.0.0.

The -multivalue-rdn option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0. The <-nodes> option was deprecated in OpenSSL 3.0, too; use -noenc instead.

The -reqexts option has been made an alias of -extensions in OpenSSL 3.2.

Since OpenSSL 3.2, generated certificates bear X.509 version 3 unless -x509v1 is given, and key identifier extensions are included by default.

Since OpenSSL 3.3, the -verify option will exit with 1 on failure.

"},{"location":"man1/openssl-req/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-rsa/","title":"openssl-rsa","text":""},{"location":"man1/openssl-rsa/#name","title":"NAME","text":"

openssl-rsa - RSA key processing command

"},{"location":"man1/openssl-rsa/#synopsis","title":"SYNOPSIS","text":"

openssl rsa [-help] [-inform DER|PEM|P12|ENGINE] [-outform DER|PEM] [-in filename|uri] [-passin arg] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-text] [-noout] [-modulus] [-traditional] [-check] [-pubin] [-pubout] [-RSAPublicKey_in] [-RSAPublicKey_out] [-pvk-strong] [-pvk-weak] [-pvk-none] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-rsa/#description","title":"DESCRIPTION","text":"

This command processes RSA keys. They can be converted between various forms and their components printed out.

"},{"location":"man1/openssl-rsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rsa/#notes","title":"NOTES","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-rsa/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To remove the pass phrase on an RSA private key:

openssl rsa -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl rsa -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl rsa -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl rsa -in key.pem -text -noout\n

To just output the public part of a private key:

openssl rsa -in key.pem -pubout -out pubkey.pem\n

Output the public part of a private key in RSAPublicKey format:

openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem\n
"},{"location":"man1/openssl-rsa/#bugs","title":"BUGS","text":"

There should be an option that automatically handles .key files, without having to manually edit them.

"},{"location":"man1/openssl-rsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-rsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-rsautl/","title":"openssl-rsautl","text":""},{"location":"man1/openssl-rsautl/#name","title":"NAME","text":"

openssl-rsautl - RSA command

"},{"location":"man1/openssl-rsautl/#synopsis","title":"SYNOPSIS","text":"

openssl rsautl [-help] [-in file] [-passin arg] [-rev] [-out file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-sign] [-verify] [-encrypt] [-decrypt] [-pkcs] [-x931] [-oaep] [-raw] [-hexdump] [-asn1parse] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-rsautl/#description","title":"DESCRIPTION","text":"

This command has been deprecated. The openssl-pkeyutl(1) command should be used instead.

This command can be used to sign, verify, encrypt and decrypt data using the RSA algorithm.

"},{"location":"man1/openssl-rsautl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rsautl/#notes","title":"NOTES","text":"

Since this command uses the RSA algorithm directly, it can only be used to sign or verify small pieces of data.

"},{"location":"man1/openssl-rsautl/#examples","title":"EXAMPLES","text":"

Examples equivalent to these can be found in the documentation for the non-deprecated openssl-pkeyutl(1) command.

Sign some data using a private key:

openssl rsautl -sign -in file -inkey key.pem -out sig\n

Recover the signed data

openssl rsautl -verify -in sig -inkey key.pem\n

Examine the raw signed data:

openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump\n\n0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world\n

The PKCS#1 block formatting is evident from this. If this was done using encrypt and decrypt the block would have been of type 2 (the second byte) and random padding data visible instead of the 0xff bytes.

It is possible to analyse the signature of certificates using this command in conjunction with openssl-asn1parse(1). Consider the self signed example in certs/pca-cert.pem. Running openssl-asn1parse(1) as follows yields:

openssl asn1parse -in pca-cert.pem\n\n   0:d=0  hl=4 l= 742 cons: SEQUENCE\n   4:d=1  hl=4 l= 591 cons:  SEQUENCE\n   8:d=2  hl=2 l=   3 cons:   cont [ 0 ]\n  10:d=3  hl=2 l=   1 prim:    INTEGER           :02\n  13:d=2  hl=2 l=   1 prim:   INTEGER           :00\n  16:d=2  hl=2 l=  13 cons:   SEQUENCE\n  18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption\n  29:d=3  hl=2 l=   0 prim:    NULL\n  31:d=2  hl=2 l=  92 cons:   SEQUENCE\n  33:d=3  hl=2 l=  11 cons:    SET\n  35:d=4  hl=2 l=   9 cons:     SEQUENCE\n  37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName\n  42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU\n ....\n 599:d=1  hl=2 l=  13 cons:  SEQUENCE\n 601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption\n 612:d=2  hl=2 l=   0 prim:   NULL\n 614:d=1  hl=3 l= 129 prim:  BIT STRING\n

The final BIT STRING contains the actual signature. It can be extracted with:

openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614\n

The certificate public key can be extracted with:

openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem\n

The signature can be analysed with:

openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin\n\n   0:d=0  hl=2 l=  32 cons: SEQUENCE\n   2:d=1  hl=2 l=  12 cons:  SEQUENCE\n   4:d=2  hl=2 l=   8 prim:   OBJECT            :md5\n  14:d=2  hl=2 l=   0 prim:   NULL\n  16:d=1  hl=2 l=  16 prim:  OCTET STRING\n     0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..\n

This is the parsed version of an ASN1 DigestInfo structure. It can be seen that the digest used was md5. The actual part of the certificate that was signed can be extracted with:

openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4\n

and its digest computed with:

openssl md5 -c tbs\nMD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5\n

which it can be seen agrees with the recovered value above.

"},{"location":"man1/openssl-rsautl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyutl(1), openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1)

"},{"location":"man1/openssl-rsautl/#history","title":"HISTORY","text":"

This command was deprecated in OpenSSL 3.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rsautl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man1/openssl-s_client/","title":"openssl-s_client","text":""},{"location":"man1/openssl-s_client/#name","title":"NAME","text":"

openssl-s_client - SSL/TLS client program

"},{"location":"man1/openssl-s_client/#synopsis","title":"SYNOPSIS","text":"

openssl s_client [-help] [-ssl_config section] [-connect host:port] [-host hostname] [-port port] [-bind host:port] [-proxy host:port] [-proxy_user userid] [-proxy_pass arg] [-unix path] [-4] [-6] [-quic] [-servername name] [-noservername] [-verify depth] [-verify_return_error] [-verify_quiet] [-verifyCAfile filename] [-verifyCApath dir] [-verifyCAstore uri] [-cert filename] [-certform DER|PEM|P12] [-cert_chain filename] [-build_chain] [-CRL filename] [-CRLform DER|PEM] [-crl_download] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pass arg] [-chainCAfile filename] [-chainCApath directory] [-chainCAstore uri] [-requestCAfile filename] [-dane_tlsa_domain domain] [-dane_tlsa_rrdata rrdata] [-dane_ee_no_namechecks] [-reconnect] [-showcerts] [-prexit] [-no-interactive] [-debug] [-trace] [-nocommands] [-adv] [-security_debug] [-security_debug_verbose] [-msg] [-timeout] [-mtu size] [-no_etm] [-no_ems] [-keymatexport label] [-keymatexportlen len] [-msgfile filename] [-nbio_test] [-state] [-nbio] [-crlf] [-ign_eof] [-no_ign_eof] [-psk_identity identity] [-psk key] [-psk_session file] [-quiet] [-sctp] [-sctp_label_bug] [-fallback_scsv] [-async] [-maxfraglen len] [-max_send_frag] [-split_send_frag] [-max_pipelines] [-read_buf] [-ignore_unexpected_eof] [-bugs] [-no_tx_cert_comp] [-no_rx_cert_comp] [-comp] [-no_comp] [-brief] [-legacy_server_connect] [-no_legacy_server_connect] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-sigalgs sigalglist] [-curves curvelist] [-cipher cipherlist] [-ciphersuites val] [-serverpref] [-starttls protocol] [-name hostname] [-xmpphost hostname] [-name hostname] [-tlsextdebug] [-no_ticket] [-sess_out filename] [-serverinfo types] [-sess_in filename] [-serverinfo types] [-status] [-alpn protocols] [-nextprotoneg protocols] [-ct] [-noct] [-ctlogfile] [-keylogfile file] [-early_data file] [-enable_pha] [-use_srtp value] [-srpuser value] [-srppass value] [-srp_lateuser] [-srp_moregroups] [-srp_strength number] [-ktls] [-tfo] [-nameopt option] [-no_ssl3] [-no_tls1] [-no_tls1_1] [-no_tls1_2] [-no_tls1_3] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-dtls] [-dtls1] [-dtls1_2] [-xkey infile] [-xcert file] [-xchain file] [-xchain_build file] [-xcertform DER|PEM]> [-xkeyform DER|PEM]> [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-bugs] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-client_renegotiation] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-legacy_server_connect] [-no_legacy_server_connect] [-no_etm] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs algs] [-client_sigalgs algs] [-groups groups] [-curves curves] [-named_curve curve] [-cipher ciphers] [-ciphersuites 1.3ciphers] [-min_protocol minprot] [-max_protocol maxprot] [-record_padding padding] [-debug_broken_protocol] [-no_middlebox] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-engine id] [-ssl_client_engine id] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-enable_server_rpk] [-enable_client_rpk] [host:port]

"},{"location":"man1/openssl-s_client/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS client which connects to a remote host using SSL/TLS. It is a very useful diagnostic tool for SSL servers.

"},{"location":"man1/openssl-s_client/#options","title":"OPTIONS","text":"

In addition to the options below, this command also supports the common and client only options documented in the \"Supported Command Line Commands\" section of the SSL_CONF_cmd(3) manual page.

"},{"location":"man1/openssl-s_client/#connected-commands-basic","title":"CONNECTED COMMANDS (BASIC)","text":"

If a connection is established with an SSL/TLS server then any data received from the server is displayed and any key presses will be sent to the server. If end of file is reached then the connection will be closed down.

When used interactively (which means neither -quiet nor -ign_eof have been given), and neither of -adv or -nocommands are given then \"Basic\" command mode is entered. In this mode certain commands are recognized which perform special operations. These commands are a letter which must appear at the start of a line. All further data after the initial letter on the line is ignored. The commands are listed below.

"},{"location":"man1/openssl-s_client/#connected-commands-advanced","title":"CONNECTED COMMANDS (ADVANCED)","text":"

If -adv has been given then \"advanced\" command mode is entered. As with basic mode, if a connection is established with an SSL/TLS server then any data received from the server is displayed and any key presses will be sent to the server. If end of file is reached then the connection will be closed down.

Special commands can be supplied by enclosing them in braces, e.g. \"{help}\" or \"{quit}\". These commands can appear anywhere in the text entered into s_client, but they are not sent to the server. Some commands can take an argument by ending the command name with \":\" and then providing the argument, e.g. \"{keyup:req}\". Some commands are only available when certain protocol versions have been negotiated.

If a newline appears at the end of a line entered into s_client then this is also sent to the server. If a command appears on a line on its own with no other text on the same line, then the newline is suppressed and not sent to the server.

The following commands are recognised.

"},{"location":"man1/openssl-s_client/#notes","title":"NOTES","text":"

This command can be used to debug SSL servers. To connect to an SSL HTTP server the command:

openssl s_client -connect servername:443\n

would typically be used (https uses port 443). If the connection succeeds then an HTTP command can be given such as \"GET /\" to retrieve a web page.

If the handshake fails then there are several possible causes, if it is nothing obvious like no client certificate then the -bugs, -ssl3, -tls1, -no_ssl3, -no_tls1 options can be tried in case it is a buggy server. In particular you should play with these options before submitting a bug report to an OpenSSL mailing list.

A frequent problem when attempting to get client certificates working is that a web client complains it has no certificates or gives an empty list to choose from. This is normally because the server is not sending the clients certificate authority in its \"acceptable CA list\" when it requests a certificate. By using this command, the CA list can be viewed and checked. However, some servers only request client authentication after a specific URL is requested. To obtain the list in this case it is necessary to use the -prexit option and send an HTTP request for an appropriate page.

If a certificate is specified on the command line using the -cert option it will not be used unless the server specifically requests a client certificate. Therefore, merely including a client certificate on the command line is no guarantee that the certificate works.

If there are problems verifying a server certificate then the -showcerts option can be used to show all the certificates sent by the server.

This command is a test tool and is designed to continue the handshake after any certificate verification errors. As a result it will accept any certificate chain (trusted or not) sent by the peer. Non-test applications should not do this as it makes them vulnerable to a MITM attack. This behaviour can be changed by with the -verify_return_error option: any verify errors are then returned aborting the handshake.

The -bind option may be useful if the server or a firewall requires connections to come from some particular address and or port.

"},{"location":"man1/openssl-s_client/#note-on-non-interactive-use","title":"Note on Non-Interactive Use","text":"

When s_client is run in a non-interactive environment (e.g., a cron job or a script without a valid stdin), it may close the connection prematurely, especially with TLS 1.3. To prevent this, you can use the -ign_eof flag, which keeps s_client running even after reaching EOF from stdin.

For example:

openssl s_client -connect <server address>:443 -tls1_3\n                 -sess_out /path/to/tls_session_params_file\n                 -ign_eof </dev/null\n

However, relying solely on -ign_eof can lead to issues if the server keeps the connection open, expecting the client to close first. In such cases, the client may hang indefinitely. This behavior is not uncommon, particularly with protocols where the server waits for a graceful disconnect from the client.

For example, when connecting to an SMTP server, the session may pause if the server expects a QUIT command before closing:

$ openssl s_client -brief -ign_eof -starttls smtp\n                   -connect <server address>:25 </dev/null\nCONNECTION ESTABLISHED\nProtocol version: TLSv1.3\nCiphersuite: TLS_AES_256_GCM_SHA384\n...\n250 CHUNKING\n[long pause]\n

To avoid such hangs, it's better to use an application-level command to initiate a clean disconnect. For SMTP, you can send a QUIT command:

printf 'QUIT\\r\\n' | openssl s_client -connect <server address>:25\n                                     -starttls smtp -brief -ign_eof\n

Similarly, for HTTP/1.1 connections, including a `Connection: close` header ensures the server closes the connection after responding:

printf 'GET / HTTP/1.1\\r\\nHost: <server address>\\r\\nConnection: close\\r\\n\\r\\n'\n    | openssl s_client -connect <server address>:443 -brief\n

These approaches help manage the connection closure gracefully and prevent hangs caused by the server waiting for the client to initiate the disconnect.

"},{"location":"man1/openssl-s_client/#bugs","title":"BUGS","text":"

Because this program has a lot of options and also because some of the techniques used are rather old, the C source for this command is rather hard to read and not a model of how things should be done. A typical SSL client program would be much simpler.

The -prexit option is a bit of a hack. We should really report information whenever a session is renegotiated.

"},{"location":"man1/openssl-s_client/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-sess_id(1), openssl-s_server(1), openssl-ciphers(1), SSL_CONF_cmd(3), SSL_CTX_set_max_send_fragment(3), SSL_CTX_set_split_send_fragment(3), SSL_CTX_set_max_pipelines(3), ossl_store-file(7)

"},{"location":"man1/openssl-s_client/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0. The -name option was added in OpenSSL 1.1.1.

The -certform option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0.

The -enable_client_rpk, -enable_server_rpk, -no_rx_cert_comp, -no_tx_cert_comp, and -tfo options were added in OpenSSL 3.2.

"},{"location":"man1/openssl-s_client/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-s_server/","title":"openssl-s_server","text":""},{"location":"man1/openssl-s_server/#name","title":"NAME","text":"

openssl-s_server - SSL/TLS server program

"},{"location":"man1/openssl-s_server/#synopsis","title":"SYNOPSIS","text":"

openssl s_server [-help] [-port +int] [-accept val] [-unix val] [-4] [-6] [-unlink] [-context val] [-verify int] [-Verify int] [-cert infile] [-cert2 infile] [-certform DER|PEM|P12] [-cert_chain infile] [-build_chain] [-serverinfo val] [-key filename|uri] [-key2 filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pass val] [-dcert infile] [-dcertform DER|PEM|P12] [-dcert_chain infile] [-dkey filename|uri] [-dkeyform DER|PEM|P12|ENGINE] [-dpass val] [-nbio_test] [-crlf] [-debug] [-msg] [-msgfile outfile] [-state] [-nocert] [-quiet] [-no_resume_ephemeral] [-www] [-WWW] [-http_server_binmode] [-no_ca_names] [-ignore_unexpected_eof] [-servername] [-servername_fatal] [-tlsextdebug] [-HTTP] [-id_prefix val] [-keymatexport val] [-keymatexportlen +int] [-CRL infile] [-CRLform DER|PEM] [-crl_download] [-chainCAfile infile] [-chainCApath dir] [-chainCAstore uri] [-verifyCAfile infile] [-verifyCApath dir] [-verifyCAstore uri] [-no_cache] [-ext_cache] [-verify_return_error] [-verify_quiet] [-ign_eof] [-no_ign_eof] [-no_etm] [-no_ems] [-status] [-status_verbose] [-status_timeout int] [-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-no_proxy addresses] [-status_url val] [-status_file infile] [-ssl_config val] [-trace] [-security_debug] [-security_debug_verbose] [-brief] [-rev] [-async] [-max_send_frag +int] [-split_send_frag +int] [-max_pipelines +int] [-naccept +int] [-read_buf +int] [-bugs] [-no_tx_cert_comp] [-no_rx_cert_comp] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs val] [-client_sigalgs val] [-groups val] [-curves val] [-named_curve val] [-cipher val] [-ciphersuites val] [-dhparam infile] [-record_padding val] [-debug_broken_protocol] [-nbio] [-psk_identity val] [-psk_hint val] [-psk val] [-psk_session file] [-srpvfile infile] [-srpuserseed val] [-timeout] [-mtu +int] [-listen] [-sctp] [-sctp_label_bug] [-use_srtp val] [-no_dhe] [-nextprotoneg val] [-alpn val] [-ktls] [-sendfile] [-zerocopy_sendfile] [-keylogfile outfile] [-recv_max_early_data int] [-max_early_data int] [-early_data] [-stateless] [-anti_replay] [-no_anti_replay] [-num_tickets] [-tfo] [-cert_comp] [-nameopt option] [-no_ssl3] [-no_tls1] [-no_tls1_1] [-no_tls1_2] [-no_tls1_3] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-dtls] [-dtls1] [-dtls1_2] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-bugs] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-client_renegotiation] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-legacy_server_connect] [-no_legacy_server_connect] [-no_etm] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs algs] [-client_sigalgs algs] [-groups groups] [-curves curves] [-named_curve curve] [-cipher ciphers] [-ciphersuites 1.3ciphers] [-min_protocol minprot] [-max_protocol maxprot] [-record_padding padding] [-debug_broken_protocol] [-no_middlebox] [-xkey infile] [-xcert file] [-xchain file] [-xchain_build file] [-xcertform DER|PEM]> [-xkeyform DER|PEM]> [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-enable_server_rpk] [-enable_client_rpk]

"},{"location":"man1/openssl-s_server/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS server which listens for connections on a given port using SSL/TLS.

"},{"location":"man1/openssl-s_server/#options","title":"OPTIONS","text":"

In addition to the options below, this command also supports the common and server only options documented \"Supported Command Line Commands\" in SSL_CONF_cmd(3)

"},{"location":"man1/openssl-s_server/#connected-commands","title":"CONNECTED COMMANDS","text":"

If a connection request is established with an SSL client and neither the -www nor the -WWW option has been used then normally any data received from the client is displayed and any key presses will be sent to the client.

Certain commands are also recognized which perform special operations. These commands are a letter which must appear at the start of a line. They are listed below.

"},{"location":"man1/openssl-s_server/#notes","title":"NOTES","text":"

This command can be used to debug SSL clients. To accept connections from a web browser the command:

openssl s_server -accept 443 -www\n

can be used for example.

Although specifying an empty list of CAs when requesting a client certificate is strictly speaking a protocol violation, some SSL clients interpret this to mean any CA is acceptable. This is useful for debugging purposes.

The session parameters can printed out using the openssl-sess_id(1) command.

"},{"location":"man1/openssl-s_server/#bugs","title":"BUGS","text":"

Because this program has a lot of options and also because some of the techniques used are rather old, the C source for this command is rather hard to read and not a model of how things should be done. A typical SSL server program would be much simpler.

The output of common ciphers is wrong: it just gives the list of ciphers that OpenSSL recognizes and the client supports.

There should be a way for this command to print out details of any unknown cipher suites a client says it supports.

"},{"location":"man1/openssl-s_server/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-sess_id(1), openssl-s_client(1), openssl-ciphers(1), SSL_CONF_cmd(3), SSL_CTX_set_max_send_fragment(3), SSL_CTX_set_split_send_fragment(3), SSL_CTX_set_max_pipelines(3), ossl_store-file(7)

"},{"location":"man1/openssl-s_server/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0.

The -allow-no-dhe-kex and -prioritize_chacha options were added in OpenSSL 1.1.1.

The -srpvfile, -srpuserseed, and -engine option were deprecated in OpenSSL 3.0.

The -enable_client_rpk, -enable_server_rpk, -no_rx_cert_comp, -no_tx_cert_comp, and -tfo options were added in OpenSSL 3.2.

"},{"location":"man1/openssl-s_server/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-s_time/","title":"openssl-s_time","text":""},{"location":"man1/openssl-s_time/#name","title":"NAME","text":"

openssl-s_time - SSL/TLS performance timing program

"},{"location":"man1/openssl-s_time/#synopsis","title":"SYNOPSIS","text":"

openssl s_time [-help] [-connect host:port] [-www page] [-cert filename] [-key filename] [-reuse] [-new] [-verify depth] [-time seconds] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-bugs] [-cipher cipherlist] [-ciphersuites val] [-nameopt option] [-cafile file] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-s_time/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS client which connects to a remote host using SSL/TLS. It can request a page from the server and includes the time to transfer the payload data in its timing measurements. It measures the number of connections within a given timeframe, the amount of data transferred (if any), and calculates the average time spent for one connection.

"},{"location":"man1/openssl-s_time/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-s_time/#notes","title":"NOTES","text":"

This command can be used to measure the performance of an SSL connection. To connect to an SSL HTTP server and get the default page the command

openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]\n

would typically be used (https uses port 443). commoncipher is a cipher to which both client and server can agree, see the openssl-ciphers(1) command for details.

If the handshake fails then there are several possible causes, if it is nothing obvious like no client certificate then the -bugs and -ssl3 options can be tried in case it is a buggy server. In particular you should play with these options before submitting a bug report to an OpenSSL mailing list.

A frequent problem when attempting to get client certificates working is that a web client complains it has no certificates or gives an empty list to choose from. This is normally because the server is not sending the clients certificate authority in its \"acceptable CA list\" when it requests a certificate. By using openssl-s_client(1) the CA list can be viewed and checked. However, some servers only request client authentication after a specific URL is requested. To obtain the list in this case it is necessary to use the -prexit option of openssl-s_client(1) and send an HTTP request for an appropriate page.

If a certificate is specified on the command line using the -cert option it will not be used unless the server specifically requests a client certificate. Therefore, merely including a client certificate on the command line is no guarantee that the certificate works.

"},{"location":"man1/openssl-s_time/#bugs","title":"BUGS","text":"

Because this program does not have all the options of the openssl-s_client(1) program to turn protocols on and off, you may not be able to measure the performance of all protocols with all servers.

The -verify option should really exit if the server verification fails.

"},{"location":"man1/openssl-s_time/#history","title":"HISTORY","text":"

The -cafile option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-s_time/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-s_client(1), openssl-s_server(1), openssl-ciphers(1), ossl_store-file(7)

"},{"location":"man1/openssl-s_time/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2021 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.

"},{"location":"man1/openssl-sess_id/","title":"openssl-sess_id","text":""},{"location":"man1/openssl-sess_id/#name","title":"NAME","text":"

openssl-sess_id - SSL/TLS session handling command

"},{"location":"man1/openssl-sess_id/#synopsis","title":"SYNOPSIS","text":"

openssl sess_id [-help] [-inform DER|PEM] [-outform DER|PEM|NSS] [-in filename] [-out filename] [-text] [-cert] [-noout] [-context ID]

"},{"location":"man1/openssl-sess_id/#description","title":"DESCRIPTION","text":"

This command processes the encoded version of the SSL session structure and optionally prints out SSL session details (for example the SSL session master key) in human readable format. Since this is a diagnostic tool that needs some knowledge of the SSL protocol to use properly, most users will not need to use it.

The precise format of the data can vary across OpenSSL versions and is not documented.

"},{"location":"man1/openssl-sess_id/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-sess_id/#output","title":"OUTPUT","text":"

Typical output:

SSL-Session:\n    Protocol  : TLSv1\n    Cipher    : 0016\n    Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED\n    Session-ID-ctx: 01000000\n    Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD\n    Key-Arg   : None\n    Start Time: 948459261\n    Timeout   : 300 (sec)\n    Verify return code 0 (ok)\n

These are described below in more detail.

"},{"location":"man1/openssl-sess_id/#notes","title":"NOTES","text":"

Since the SSL session output contains the master key it is possible to read the contents of an encrypted session using this information. Therefore, appropriate security precautions should be taken if the information is being output by a \"real\" application. This is however strongly discouraged and should only be used for debugging purposes.

"},{"location":"man1/openssl-sess_id/#bugs","title":"BUGS","text":"

The cipher and start time should be printed out in human readable form.

"},{"location":"man1/openssl-sess_id/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ciphers(1), openssl-s_server(1)

"},{"location":"man1/openssl-sess_id/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man1/openssl-smime/","title":"openssl-smime","text":""},{"location":"man1/openssl-smime/#name","title":"NAME","text":"

openssl-smime - S/MIME command

"},{"location":"man1/openssl-smime/#synopsis","title":"SYNOPSIS","text":"

openssl smime [-help] [-encrypt] [-decrypt] [-sign] [-resign] [-verify] [-pk7out] [-binary] [-crlfeol] [-cipher] [-in file] [-certfile file] [-signer file] [-nointern] [-noverify] [-nochain] [-nosigs] [-nocerts] [-noattr] [-nodetach] [-nosmimecap] [-recip _ file_] [-inform DER|PEM|SMIME] [-outform DER|PEM|SMIME] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-inkey filename|uri] [-out file] [-content file] [-to addr] [-from ad] [-subject s] [-text] [-indef] [-noindef] [-stream] [-md digest] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-engine id] [-rand files] [-writerand file] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq] [-config configfile] recipcert ...

"},{"location":"man1/openssl-smime/#description","title":"DESCRIPTION","text":"

This command handles S/MIME mail. It can encrypt, decrypt, sign and verify S/MIME messages.

"},{"location":"man1/openssl-smime/#options","title":"OPTIONS","text":"

There are six operation options that set the type of operation to be performed: -encrypt, -decrypt, -sign, -resign, -verify, and -pk7out. These are mutually exclusive. The meaning of the other options varies according to the operation type.

"},{"location":"man1/openssl-smime/#notes","title":"NOTES","text":"

The MIME message must be sent without any blank lines between the headers and the output. Some mail programs will automatically add a blank line. Piping the mail directly to sendmail is one way to achieve the correct format.

The supplied message to be signed or encrypted must include the necessary MIME headers or many S/MIME clients won't display it properly (if at all). You can use the -text option to automatically add plain text headers.

A \"signed and encrypted\" message is one where a signed message is then encrypted. This can be produced by encrypting an already signed message: see the examples section.

This version of the program only allows one signer per message but it will verify multiple signers on received messages. Some S/MIME clients choke if a message contains multiple signers. It is possible to sign messages \"in parallel\" by signing an already signed message.

The options -encrypt and -decrypt reflect common usage in S/MIME clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 encrypted data is used for other purposes.

The -resign option uses an existing message digest when adding a new signer. This means that attributes must be present in at least one existing signer using the same message digest or this operation will fail.

The -stream and -indef options enable streaming I/O support. As a result the encoding is BER using indefinite length constructed encoding and no longer DER. Streaming is supported for the -encrypt operation and the -sign operation if the content is not detached.

Streaming is always used for the -sign operation with detached data but since the content is no longer part of the PKCS#7 structure the encoding remains DER.

"},{"location":"man1/openssl-smime/#exit-codes","title":"EXIT CODES","text":""},{"location":"man1/openssl-smime/#examples","title":"EXAMPLES","text":"

Create a cleartext signed message:

openssl smime -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem\n

Create an opaque signed message:

openssl smime -sign -in message.txt -text -out mail.msg -nodetach \\\n       -signer mycert.pem\n

Create a signed message, include some additional certificates and read the private key from another file:

openssl smime -sign -in in.txt -text -out mail.msg \\\n       -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem\n

Create a signed message with two signers:

openssl smime -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -signer othercert.pem\n

Send a signed message under Unix directly to sendmail, including headers:

openssl smime -sign -in in.txt -text -signer mycert.pem \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed message\" | sendmail someone@somewhere\n

Verify a message and extract the signer's certificate if successful:

openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt\n

Send encrypted mail using triple DES:

openssl smime -encrypt -in in.txt -out mail.msg -from steve@openssl.org \\\n       -to someone@somewhere -subject \"Encrypted message\" \\\n       -des3 user.pem\n

Sign and encrypt mail:

openssl smime -sign -in ml.txt -signer my.pem -text \\\n       | openssl smime -encrypt -out mail.msg \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed and Encrypted message\" -des3 user.pem\n

Note: the encryption command does not include the -text option because the message being encrypted already has MIME headers.

Decrypt mail:

openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem\n

The output from Netscape form signing is a PKCS#7 structure with the detached signature format. You can use this program to verify the signature by line wrapping the base64 encoded structure and surrounding it with:

-----BEGIN PKCS7-----\n-----END PKCS7-----\n

and using the command:

openssl smime -verify -inform PEM -in signature.pem -content content.txt\n

Alternatively you can base64 decode the signature and use:

openssl smime -verify -inform DER -in signature.der -content content.txt\n

Create an encrypted message using 128 bit Camellia:

openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem\n

Add a signer to an existing message:

openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg\n
"},{"location":"man1/openssl-smime/#bugs","title":"BUGS","text":"

The MIME parser isn't very clever: it seems to handle most messages that I've thrown at it but it may choke on others.

The code currently will only write out the signer's certificate to a file: if the signer has a separate encryption certificate this must be manually extracted. There should be some heuristic that determines the correct encryption certificate.

Ideally a database should be maintained of a certificates for each email address.

The code doesn't currently take note of the permitted symmetric encryption algorithms as supplied in the SMIMECapabilities signed attribute. This means the user has to manually include the correct encryption algorithm. It should store the list of permitted ciphers in a database and only use those.

No revocation checking is done on the signer's certificate.

The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 structures may cause parsing errors.

"},{"location":"man1/openssl-smime/#see-also","title":"SEE ALSO","text":"

ossl_store-file(7)

"},{"location":"man1/openssl-smime/#history","title":"HISTORY","text":"

The default encryption cipher was changed from 3DES to AES-256 in OpenSSL 3.5.

The use of multiple -signer options and the -resign command were first added in OpenSSL 1.0.0

The -no_alt_chains option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-smime/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-speed/","title":"openssl-speed","text":""},{"location":"man1/openssl-speed/#name","title":"NAME","text":"

openssl-speed - test library performance

"},{"location":"man1/openssl-speed/#synopsis","title":"SYNOPSIS","text":"

openssl speed [-help] [-config filename] [-elapsed] [-evp algo] [-hmac algo] [-cmac algo] [-mb] [-aead] [-kem-algorithms] [-signature-algorithms] [-multi num] [-async_jobs num] [-misalign num] [-decrypt] [-primes num] [-seconds num] [-bytes num] [-mr] [-mlock] [-testmode] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [algorithm ...]

"},{"location":"man1/openssl-speed/#description","title":"DESCRIPTION","text":"

This command is used to test the performance of cryptographic algorithms.

"},{"location":"man1/openssl-speed/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-speed/#bugs","title":"BUGS","text":"

The algorithm can be selected only from a pre-compiled subset of things that the openssl speed command knows about. To test any additional digest or cipher algorithm supported by OpenSSL use the -evp option.

There is no way to test the speed of any additional public key algorithms supported by third party providers with the openssl speed command.

"},{"location":"man1/openssl-speed/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

DSA512 was removed in OpenSSL 3.2.

The -testmode option was added in OpenSSL 3.4.

"},{"location":"man1/openssl-speed/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-spkac/","title":"openssl-spkac","text":""},{"location":"man1/openssl-spkac/#name","title":"NAME","text":"

openssl-spkac - SPKAC printing and generating command

"},{"location":"man1/openssl-spkac/#synopsis","title":"SYNOPSIS","text":"

openssl spkac [-help] [-in filename] [-out filename] [-digest digest] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-challenge string] [-pubkey] [-spkac spkacname] [-spksect section] [-noout] [-verify] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-spkac/#description","title":"DESCRIPTION","text":"

This command processes Netscape signed public key and challenge (SPKAC) files. It can print out their contents, verify the signature and produce its own SPKACs from a supplied private key.

"},{"location":"man1/openssl-spkac/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-spkac/#examples","title":"EXAMPLES","text":"

Print out the contents of an SPKAC:

openssl spkac -in spkac.cnf\n

Verify the signature of an SPKAC:

openssl spkac -in spkac.cnf -noout -verify\n

Create an SPKAC using the challenge string \"hello\":

openssl spkac -key key.pem -challenge hello -out spkac.cnf\n

Example of an SPKAC, (long lines split up for clarity):

SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA\\\n1cCoq2Wa3Ixs47uI7FPVwHVIPDx5yso105Y6zpozam135a\\\n8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03uPFoQIDAQAB\\\nFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJ\\\nh1bEIYuc2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnD\\\ndq+NQ3F+X4deMx9AaEglZtULwV4=\n
"},{"location":"man1/openssl-spkac/#notes","title":"NOTES","text":"

A created SPKAC with suitable DN components appended can be fed to openssl-ca(1).

SPKACs are typically generated by Netscape when a form is submitted containing the KEYGEN tag as part of the certificate enrollment process.

The challenge string permits a primitive form of proof of possession of private key. By checking the SPKAC signature and a random challenge string some guarantee is given that the user knows the private key corresponding to the public key being certified. This is important in some applications. Without this it is possible for a previous SPKAC to be used in a \"replay attack\".

"},{"location":"man1/openssl-spkac/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ca(1)

"},{"location":"man1/openssl-spkac/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -digest option was added in OpenSSL 3.0.

"},{"location":"man1/openssl-spkac/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-srp/","title":"openssl-srp","text":""},{"location":"man1/openssl-srp/#name","title":"NAME","text":"

openssl-srp - maintain SRP password file

"},{"location":"man1/openssl-srp/#synopsis","title":"SYNOPSIS","text":"

openssl srp [-help] [-verbose] [-add] [-modify] [-delete] [-list] [-name section] [-srpvfile file] [-gn identifier] [-userinfo text] [-passin arg] [-passout arg] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile] [user ...]

"},{"location":"man1/openssl-srp/#description","title":"DESCRIPTION","text":"

This command is deprecated. It is used to maintain an SRP (secure remote password) file. At most one of the -add, -modify, -delete, and -list options can be specified. These options take zero or more usernames as parameters and perform the appropriate operation on the SRP file. For -list, if no user is given then all users are displayed.

The configuration file to use, and the section within the file, can be specified with the -config and -name flags, respectively.

"},{"location":"man1/openssl-srp/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-srp/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-srp/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2021 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.

"},{"location":"man1/openssl-storeutl/","title":"openssl-storeutl","text":""},{"location":"man1/openssl-storeutl/#name","title":"NAME","text":"

openssl-storeutl - STORE command

"},{"location":"man1/openssl-storeutl/#synopsis","title":"SYNOPSIS","text":"

openssl storeutl [-help] [-out file] [-noout] [-passin arg] [-text arg] [-r] [-certs] [-keys] [-crls] [-subject arg] [-issuer arg] [-serial arg] [-alias arg] [-fingerprint arg] [-digest] [-engine id] [-provider name] [-provider-path path] [-propquery propq] uri

"},{"location":"man1/openssl-storeutl/#description","title":"DESCRIPTION","text":"

This command can be used to display the contents (after decryption as the case may be) fetched from the given URI.

"},{"location":"man1/openssl-storeutl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-storeutl/#see-also","title":"SEE ALSO","text":"

openssl(1)

"},{"location":"man1/openssl-storeutl/#history","title":"HISTORY","text":"

This command was added in OpenSSL 1.1.1.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-storeutl/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man1/openssl-ts/","title":"openssl-ts","text":""},{"location":"man1/openssl-ts/#name","title":"NAME","text":"

openssl-ts - Time Stamping Authority command

"},{"location":"man1/openssl-ts/#synopsis","title":"SYNOPSIS","text":"

openssl ts -help

openssl ts -query [-config configfile] [-data file_to_hash] [-digest digest_bytes] [-digest] [-tspolicy object_id] [-no_nonce] [-cert] [-in request.tsq] [-out request.tsq] [-text] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

openssl ts -reply [-config configfile] [-section tsa_section] [-queryfile request.tsq] [-passin password_src] [-signer tsa_cert.pem] [-inkey filename|uri] [-digest] [-chain certs_file.pem] [-tspolicy object_id] [-in response.tsr] [-token_in] [-out response.tsr] [-token_out] [-text] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

openssl ts -verify [-data file_to_hash] [-digest digest_bytes] [-queryfile request.tsq] [-in response.tsr] [-token_in] [-untrusted files|uris] [-CAfile file] [-CApath dir] [-CAstore uri] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ts/#description","title":"DESCRIPTION","text":"

This command is a basic Time Stamping Authority (TSA) client and server application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A TSA can be part of a PKI deployment and its role is to provide long term proof of the existence of a certain datum before a particular time. Here is a brief description of the protocol:

  1. The TSA client computes a one-way hash value for a data file and sends the hash to the TSA.
  2. The TSA attaches the current date and time to the received hash value, signs them and sends the timestamp token back to the client. By creating this token the TSA certifies the existence of the original data file at the time of response generation.
  3. The TSA client receives the timestamp token and verifies the signature on it. It also checks if the token contains the same hash value that it had sent to the TSA.

There is one DER encoded protocol data unit defined for transporting a timestamp request to the TSA and one for sending the timestamp response back to the client. This command has three main functions: creating a timestamp request based on a data file, creating a timestamp response based on a request, verifying if a response corresponds to a particular request or a data file.

There is no support for sending the requests/responses automatically over HTTP or TCP yet as suggested in RFC 3161. The users must send the requests either by ftp or e-mail.

"},{"location":"man1/openssl-ts/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ts/#timestamp-request-generation","title":"Timestamp Request generation","text":"

The -query command can be used for creating and printing a timestamp request with the following options:

"},{"location":"man1/openssl-ts/#timestamp-response-generation","title":"Timestamp Response generation","text":"

A timestamp response (TimeStampResp) consists of a response status and the timestamp token itself (ContentInfo), if the token generation was successful. The -reply command is for creating a timestamp response or timestamp token based on a request and printing the response/token in human-readable format. If -token_out is not specified the output is always a timestamp response (TimeStampResp), otherwise it is a timestamp token (ContentInfo).

"},{"location":"man1/openssl-ts/#timestamp-response-verification","title":"Timestamp Response verification","text":"

The -verify command is for verifying if a timestamp response or timestamp token is valid and matches a particular timestamp request or data file. The -verify command does not use the configuration file.

"},{"location":"man1/openssl-ts/#configuration-file-options","title":"CONFIGURATION FILE OPTIONS","text":"

The -query and -reply commands make use of a configuration file. See config(5) for a general description of the syntax of the config file. The -query command uses only the symbolic OID names section and it can work without it. However, the -reply command needs the config file for its operation.

When there is a command line switch equivalent of a variable the switch always overrides the settings in the config file.

"},{"location":"man1/openssl-ts/#examples","title":"EXAMPLES","text":"

All the examples below presume that OPENSSL_CONF is set to a proper configuration file, e.g. the example configuration file openssl/apps/openssl.cnf will do.

"},{"location":"man1/openssl-ts/#timestamp-request","title":"Timestamp Request","text":"

To create a timestamp request for design1.txt with SHA-256 digest, without nonce and policy, and without requirement for a certificate in the response:

openssl ts -query -data design1.txt -no_nonce \\\n      -out design1.tsq\n

To create a similar timestamp request with specifying the message imprint explicitly:

openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \\\n       -no_nonce -out design1.tsq\n

To print the content of the previous request in human readable format:

openssl ts -query -in design1.tsq -text\n

To create a timestamp request which includes the SHA-512 digest of design2.txt, requests the signer certificate and nonce, and specifies a policy id (assuming the tsa_policy1 name is defined in the OID section of the config file):

openssl ts -query -data design2.txt -sha512 \\\n      -tspolicy tsa_policy1 -cert -out design2.tsq\n
"},{"location":"man1/openssl-ts/#timestamp-response","title":"Timestamp Response","text":"

Before generating a response a signing certificate must be created for the TSA that contains the timeStamping critical extended key usage extension without any other key usage extensions. You can add this line to the user certificate section of the config file to generate a proper certificate;

extendedKeyUsage = critical,timeStamping\n

See openssl-req(1), openssl-ca(1), and openssl-x509(1) for instructions. The examples below assume that cacert.pem contains the certificate of the CA, tsacert.pem is the signing certificate issued by cacert.pem and tsakey.pem is the private key of the TSA.

To create a timestamp response for a request:

openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \\\n      -signer tsacert.pem -out design1.tsr\n

If you want to use the settings in the config file you could just write:

openssl ts -reply -queryfile design1.tsq -out design1.tsr\n

To print a timestamp reply to stdout in human readable format:

openssl ts -reply -in design1.tsr -text\n

To create a timestamp token instead of timestamp response:

openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out\n

To print a timestamp token to stdout in human readable format:

openssl ts -reply -in design1_token.der -token_in -text -token_out\n

To extract the timestamp token from a response:

openssl ts -reply -in design1.tsr -out design1_token.der -token_out\n

To add 'granted' status info to a timestamp token thereby creating a valid response:

openssl ts -reply -in design1_token.der -token_in -out design1.tsr\n
"},{"location":"man1/openssl-ts/#timestamp-verification","title":"Timestamp Verification","text":"

To verify a timestamp reply against a request:

openssl ts -verify -queryfile design1.tsq -in design1.tsr \\\n      -CAfile cacert.pem -untrusted tsacert.pem\n

To verify a timestamp reply that includes the certificate chain:

openssl ts -verify -queryfile design2.tsq -in design2.tsr \\\n      -CAfile cacert.pem\n

To verify a timestamp token against the original data file:

openssl ts -verify -data design2.txt -in design2.tsr \\\n      -CAfile cacert.pem\n

To verify a timestamp token against a message imprint:

openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \\\n       -in design2.tsr -CAfile cacert.pem\n

You could also look at the 'test' directory for more examples.

"},{"location":"man1/openssl-ts/#bugs","title":"BUGS","text":""},{"location":"man1/openssl-ts/#history","title":"HISTORY","text":"

OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved seeding mechanism. The new seeding mechanism makes it unnecessary to define a RANDFILE for saving and restoring randomness. This option is retained mainly for compatibility reasons.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-ts/#see-also","title":"SEE ALSO","text":"

openssl(1), tsget(1), openssl-req(1), openssl-x509(1), openssl-ca(1), openssl-genrsa(1), config(5), ossl_store-file(7)

"},{"location":"man1/openssl-ts/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man1/openssl-verification-options/","title":"openssl-verification-options","text":""},{"location":"man1/openssl-verification-options/#name","title":"NAME","text":"

openssl-verification-options - generic X.509 certificate verification options

"},{"location":"man1/openssl-verification-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-verification-options/#description","title":"DESCRIPTION","text":"

There are many situations where X.509 certificates are verified within the OpenSSL libraries and in various OpenSSL commands.

Certificate verification is implemented by X509_verify_cert(3). It is a complicated process consisting of a number of steps and depending on numerous options. The most important of them are detailed in the following sections.

In a nutshell, a valid chain of certificates needs to be built up and verified starting from the target certificate that is to be verified and ending in a certificate that due to some policy is trusted. Verification is done relative to the given purpose, which is the intended use of the target certificate, such as SSL server, or by default for any purpose.

The details of how each OpenSSL command handles errors are documented on the specific command page.

DANE support is documented in openssl-s_client(1), SSL_CTX_dane_enable(3), SSL_set1_host(3), X509_VERIFY_PARAM_set_flags(3), and X509_check_host(3).

"},{"location":"man1/openssl-verification-options/#trust-anchors","title":"Trust Anchors","text":"

In general, according to RFC 4158 and RFC 5280, a trust anchor is any public key and related subject distinguished name (DN) that for some reason is considered trusted and thus is acceptable as the root of a chain of certificates.

In practice, trust anchors are given in the form of certificates, where their essential fields are the public key and the subject DN. In addition to the requirements in RFC 5280, OpenSSL checks the validity period of such certificates and makes use of some further fields. In particular, the subject key identifier extension, if present, is used for matching trust anchors during chain building.

In the most simple and common case, trust anchors are by default all self-signed \"root\" CA certificates that are placed in the trust store, which is a collection of certificates that are trusted for certain uses. This is akin to what is used in the trust stores of Mozilla Firefox, or Apple's and Microsoft's certificate stores, ...

From the OpenSSL perspective, a trust anchor is a certificate that should be augmented with an explicit designation for which uses of a target certificate the certificate may serve as a trust anchor. In PEM encoding, this is indicated by the TRUSTED CERTIFICATE string. Such a designation provides a set of positive trust attributes explicitly stating trust for the listed purposes and/or a set of negative trust attributes explicitly rejecting the use for the listed purposes. The purposes are encoded using the values defined for the extended key usages (EKUs) that may be given in X.509 extensions of end-entity certificates. See also the \"Extended Key Usage\" section below.

The currently recognized uses are clientAuth (SSL client use), serverAuth (SSL server use), emailProtection (S/MIME email use), codeSigning (object signer use), OCSPSigning (OCSP responder use), OCSP (OCSP request use), timeStamping (TSA server use), and anyExtendedKeyUsage. As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or enables all uses when trusted.

A certificate, which may be CA certificate or an end-entity certificate, is considered a trust anchor for the given use if and only if all the following conditions hold:

"},{"location":"man1/openssl-verification-options/#certification-path-building","title":"Certification Path Building","text":"

First, a certificate chain is built up starting from the target certificate and ending in a trust anchor.

The chain is built up iteratively, looking up in turn a certificate with suitable key usage that matches as an issuer of the current \"subject\" certificate as described below. If there is such a certificate, the first one found that is currently valid is taken, otherwise the one that expired most recently of all such certificates. For efficiency, no backtracking is performed, thus any further candidate issuer certificates that would match equally are ignored.

When a self-signed certificate has been added, chain construction stops. In this case it must fully match a trust anchor, otherwise chain building fails.

A candidate issuer certificate matches a subject certificate if all of the following conditions hold:

The lookup first searches for issuer certificates in the trust store. If it does not find a match there it consults the list of untrusted (\"intermediate\" CA) certificates, if provided.

"},{"location":"man1/openssl-verification-options/#certification-path-validation","title":"Certification Path Validation","text":"

When the certificate chain building process was successful the chain components and their links are checked thoroughly.

The first step is to check that each certificate is well-formed. Part of these checks are enabled only if the -x509_strict option is given.

The second step is to check the extensions of every untrusted certificate for consistency with the supplied purpose. If the -purpose option is not given then no such checks are done except for SSL/TLS connection setup, where by default sslserver or sslclient, are checked. The target or \"leaf\" certificate, as well as any other untrusted certificates, must have extensions compatible with the specified purpose. All certificates except the target or \"leaf\" must also be valid CA certificates. The precise extensions required are described in more detail in \"CERTIFICATE EXTENSIONS\" in openssl-x509(1).

The third step is to check the trust settings on the last certificate (which typically is a self-signed root CA certificate). It must be trusted for the given use. For compatibility with previous versions of OpenSSL, a self-signed certificate with no trust attributes is considered to be valid for all uses.

The fourth, and final, step is to check the validity of the certificate chain. For each element in the chain, including the root CA certificate, the validity period as specified by the notBefore and notAfter fields is checked against the current system time. The -attime flag may be used to use a reference time other than \"now.\" The certificate signature is checked as well (except for the signature of the typically self-signed root CA certificate, which is verified only if the -check_ss_sig option is given). When verifying a certificate signature the keyUsage extension (if present) of the candidate issuer certificate is checked to permit digitalSignature for signing proxy certificates or to permit keyCertSign for signing other certificates, respectively. If all operations complete successfully then certificate is considered valid. If any operation fails then the certificate is not valid.

"},{"location":"man1/openssl-verification-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-verification-options/#trusted-certificate-options","title":"Trusted Certificate Options","text":"

The following options specify how to supply the certificates that can be used as trust anchors for certain uses. As mentioned, a collection of such certificates is called a trust store.

Note that OpenSSL does not provide a default set of trust anchors. Many Linux distributions include a system default and configure OpenSSL to point to that. Mozilla maintains an influential trust store that can be found at https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/.

The certificates to add to the trust store can be specified using following options.

"},{"location":"man1/openssl-verification-options/#verification-options","title":"Verification Options","text":"

The certificate verification can be fine-tuned with the following flags.

"},{"location":"man1/openssl-verification-options/#extended-verification-options","title":"Extended Verification Options","text":"

Sometimes there may be more than one certificate chain leading to an end-entity certificate. This usually happens when a root or intermediate CA signs a certificate for another a CA in other organization. Another reason is when a CA might have intermediates that use two different signature formats, such as a SHA-1 and a SHA-256 digest.

The following options can be used to provide data that will allow the OpenSSL command to generate an alternative chain.

"},{"location":"man1/openssl-verification-options/#certificate-extensions","title":"Certificate Extensions","text":"

Options like -purpose lead to checking the certificate extensions, which determine what the target certificate and intermediate CA certificates can be used for.

"},{"location":"man1/openssl-verification-options/#basic-constraints","title":"Basic Constraints","text":"

The basicConstraints extension CA flag is used to determine whether the certificate can be used as a CA. If the CA flag is true then it is a CA, if the CA flag is false then it is not a CA. All CAs should have the CA flag set to true.

If the basicConstraints extension is absent, which includes the case that it is an X.509v1 certificate, then the certificate is considered to be a \"possible CA\" and other extensions are checked according to the intended use of the certificate. The treatment of certificates without basicConstraints as a CA is presently supported, but this could change in the future.

"},{"location":"man1/openssl-verification-options/#key-usage","title":"Key Usage","text":"

If the keyUsage extension is present then additional restraints are made on the uses of the certificate. A CA certificate must have the keyCertSign bit set if the keyUsage extension is present.

"},{"location":"man1/openssl-verification-options/#extended-key-usage","title":"Extended Key Usage","text":"

The extKeyUsage (EKU) extension places additional restrictions on the certificate uses. If this extension is present (whether critical or not) the key can only be used for the purposes specified.

A complete description of each check is given below. The comments about basicConstraints and keyUsage and X.509v1 certificates above apply to all CA certificates.

"},{"location":"man1/openssl-verification-options/#bugs","title":"BUGS","text":"

The issuer checks still suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that trusted certificates with matching subject name must appear in a file (as specified by the -CAfile option), a directory (as specified by -CApath), or a store (as specified by -CAstore). If there are multiple such matches, possibly in multiple locations, only the first one (in the mentioned order of locations) is recognised.

"},{"location":"man1/openssl-verification-options/#see-also","title":"SEE ALSO","text":"

X509_verify_cert(3), openssl-verify(1), openssl-ocsp(1), openssl-ts(1), openssl-s_client(1), openssl-s_server(1), openssl-smime(1), openssl-cmp(1), openssl-cms(1)

"},{"location":"man1/openssl-verification-options/#history","title":"HISTORY","text":"

The checks enabled by -x509_strict have been extended in OpenSSL 3.0.

"},{"location":"man1/openssl-verification-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-verify/","title":"openssl-verify","text":""},{"location":"man1/openssl-verify/#name","title":"NAME","text":"

openssl-verify - certificate verification command

"},{"location":"man1/openssl-verify/#synopsis","title":"SYNOPSIS","text":"

openssl verify [-help] [-CRLfile filename|uri] [-crl_download] [-show_chain] [-verbose] [-trusted filename|uri] [-untrusted filename|uri] [-vfyopt nm:v] [-nameopt option] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-engine id] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq] [--] [certificate ...]

"},{"location":"man1/openssl-verify/#description","title":"DESCRIPTION","text":"

This command verifies certificate chains. If a certificate chain has multiple problems, this program attempts to display all of them.

"},{"location":"man1/openssl-verify/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-verify/#diagnostics","title":"DIAGNOSTICS","text":"

When a verify operation fails the output messages can be somewhat cryptic. The general form of the error message is:

server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)\nerror 24 at 1 depth lookup:invalid CA certificate\n

The first line contains the name of the certificate being verified followed by the subject name of the certificate. The second line contains the error number and the depth. The depth is number of the certificate being verified when a problem was detected starting with zero for the target (\"leaf\") certificate itself then 1 for the CA that signed the target certificate and so on. Finally a textual version of the error number is presented.

A list of the error codes and messages can be found in X509_STORE_CTX_get_error(3); the full list is defined in the header file <openssl/x509_vfy.h>.

This command ignores many errors, in order to allow all the problems with a certificate chain to be determined.

"},{"location":"man1/openssl-verify/#see-also","title":"SEE ALSO","text":"

openssl-verification-options(1), openssl-x509(1), ossl_store-file(7)

"},{"location":"man1/openssl-verify/#history","title":"HISTORY","text":"

The -show_chain option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-verify/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man1/openssl-version/","title":"openssl-version","text":""},{"location":"man1/openssl-version/#name","title":"NAME","text":"

openssl-version - print OpenSSL version information

"},{"location":"man1/openssl-version/#synopsis","title":"SYNOPSIS","text":"

openssl version [-help] [-a] [-v] [-b] [-o] [-f] [-p] [-d] [-e] [-m] [-r] [-c] [-w]

"},{"location":"man1/openssl-version/#description","title":"DESCRIPTION","text":"

This command is used to print out version information about OpenSSL.

"},{"location":"man1/openssl-version/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-version/#history","title":"HISTORY","text":"

In OpenSSL versions prior to 3.4, OpenSSL had a limitation regarding the OPENSSLDIR, MODULESDIR and ENGINESDIR build time macros. These macros were defined at build time, and represented filesystem paths. This is common practice on unix like systems, as there was an expectation that a given build would be installed to a pre-determined location. On Windows however, there is no such expectation, as libraries can be installed to arbitrary locations. OSSL_WINCTX was introduced as a new build time variable to define a set of registry keys identified by the name openssl-<version>-<ctx>, in which the <version> value is derived from the version string in the openssl source, and the <ctx> extension is derived from the OSSL_WINCTX variable. The values of OPENSSLDIR, ENGINESDIR and MODULESDIR can be set to various paths underneath this key to break the requirement to predict the installation path at build time.

"},{"location":"man1/openssl-version/#notes","title":"NOTES","text":"

The output of openssl version -a would typically be used when sending in a bug report.

"},{"location":"man1/openssl-version/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl-x509/","title":"openssl-x509","text":""},{"location":"man1/openssl-x509/#name","title":"NAME","text":"

openssl-x509 - Certificate display and signing command

"},{"location":"man1/openssl-x509/#synopsis","title":"SYNOPSIS","text":"

openssl x509 [-help] [-in filename|uri] [-passin arg] [-new] [-x509toreq] [-req] [-copy_extensions arg] [-inform DER|PEM] [-vfyopt nm:v] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-signkey filename|uri] [-out filename] [-outform DER|PEM] [-nocert] [-noout] [-dateopt] [-text] [-certopt option] [-fingerprint] [-alias] [-serial] [-startdate] [-enddate] [-dates] [-subject] [-issuer] [-nameopt option] [-email] [-hash] [-subject_hash] [-subject_hash_old] [-issuer_hash] [-issuer_hash_old] [-ext extensions] [-ocspid] [-ocsp_uri] [-purpose] [-pubkey] [-modulus] [-checkend num] [-checkhost host] [-checkemail host] [-checkip ipaddr] [-set_serial n] [-next_serial] [-not_before date] [-not_after date] [-days arg] [-preserve_dates] [-set_issuer arg] [-set_subject arg] [-subj arg] [-force_pubkey filename] [-clrext] [-extfile filename] [-extensions section] [-sigopt nm:v] [-badsig] [-digest] [-CA filename|uri] [-CAform DER|PEM|P12] [-CAkey filename|uri] [-CAkeyform DER|PEM|P12|ENGINE] [-CAserial filename] [-CAcreateserial] [-trustout] [-setalias arg] [-clrtrust] [-addtrust arg] [-clrreject] [-addreject arg] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-x509/#description","title":"DESCRIPTION","text":"

This command is a multi-purposes certificate handling command. It can be used to print certificate information, convert certificates to various forms, edit certificate trust settings, generate certificates from scratch or from certification requests and then self-signing them or signing them like a \"micro CA\".

Generated certificates bear X.509 version 3. Unless specified otherwise, key identifier extensions are included as described in x509v3_config(5).

Since there are a large number of options they will split up into various sections.

"},{"location":"man1/openssl-x509/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-x509/#input-output-and-general-purpose-options","title":"Input, Output, and General Purpose Options","text":""},{"location":"man1/openssl-x509/#certificate-printing-options","title":"Certificate Printing Options","text":"

Note: the -alias and -purpose options are also printing options but are described in the \"Trust Settings\" section.

"},{"location":"man1/openssl-x509/#certificate-checking-options","title":"Certificate Checking Options","text":""},{"location":"man1/openssl-x509/#certificate-output-options","title":"Certificate Output Options","text":""},{"location":"man1/openssl-x509/#micro-ca-options","title":"Micro-CA Options","text":""},{"location":"man1/openssl-x509/#trust-settings","title":"Trust Settings","text":"

A trusted certificate is an ordinary certificate which has several additional pieces of information attached to it such as the permitted and prohibited uses of the certificate and possibly an \"alias\" (nickname).

Normally when a certificate is being verified at least one certificate must be \"trusted\". By default a trusted certificate must be stored locally and must be a root CA: any certificate chain ending in this CA is then usable for any purpose.

Trust settings currently are only used with a root CA. They allow a finer control over the purposes the root CA can be used for. For example, a CA may be trusted for SSL client but not SSL server use.

See openssl-verification-options(1) for more information on the meaning of trust settings.

Future versions of OpenSSL will recognize trust settings on any certificate: not just root CAs.

"},{"location":"man1/openssl-x509/#generic-options","title":"Generic options","text":""},{"location":"man1/openssl-x509/#text-printing-flags","title":"Text Printing Flags","text":"

As well as customising the name printing format, it is also possible to customise the actual fields printed using the certopt option when the text option is present. The default behaviour is to print all fields.

"},{"location":"man1/openssl-x509/#examples","title":"EXAMPLES","text":"

Note: in these examples the '\\' means the example should be all on one line.

Print the contents of a certificate:

openssl x509 -in cert.pem -noout -text\n

Print the \"Subject Alternative Name\" extension of a certificate:

openssl x509 -in cert.pem -noout -ext subjectAltName\n

Print more extensions of a certificate:

openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType\n

Print the certificate serial number:

openssl x509 -in cert.pem -noout -serial\n

Print the certificate subject name:

openssl x509 -in cert.pem -noout -subject\n

Print the certificate subject name in RFC2253 form:

openssl x509 -in cert.pem -noout -subject -nameopt RFC2253\n

Print the certificate subject name in oneline form on a terminal supporting UTF8:

openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb\n

Print the certificate SHA1 fingerprint:

openssl x509 -sha1 -in cert.pem -noout -fingerprint\n

Convert a certificate from PEM to DER format:

openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER\n

Convert a certificate to a certificate request:

openssl x509 -x509toreq -in cert.pem -out req.pem -key key.pem\n

Convert a certificate request into a self-signed certificate using extensions for a CA:

openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \\\n       -key key.pem -out cacert.pem\n

Sign a certificate request using the CA certificate above and add user certificate extensions:

openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \\\n       -CA cacert.pem -CAkey key.pem -CAcreateserial\n

Set a certificate to be trusted for SSL client use and change set its alias to \"Steve's Class 1 CA\"

openssl x509 -in cert.pem -addtrust clientAuth \\\n       -setalias \"Steve's Class 1 CA\" -out trust.pem\n
"},{"location":"man1/openssl-x509/#notes","title":"NOTES","text":"

The conversion to UTF8 format used with the name options assumes that T61Strings use the ISO8859-1 character set. This is wrong but Netscape and MSIE do this as do many certificates. So although this is incorrect it is more likely to print the majority of certificates correctly.

The -email option searches the subject name and the subject alternative name extension. Only unique email addresses will be printed out: it will not print the same address more than once.

"},{"location":"man1/openssl-x509/#bugs","title":"BUGS","text":"

It is possible to produce invalid certificates or requests by specifying the wrong private key, using unsuitable X.509 extensions, or using inconsistent options in some cases: these should be checked.

There should be options to explicitly set such things as start and end dates rather than an offset from the current time.

"},{"location":"man1/openssl-x509/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-req(1), openssl-ca(1), openssl-genrsa(1), openssl-gendsa(1), openssl-verify(1), x509v3_config(5)

"},{"location":"man1/openssl-x509/#history","title":"HISTORY","text":"

The hash algorithm used in the -subject_hash and -issuer_hash options before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical version of the DN using SHA1. This means that any directories using the old form must have their links rebuilt using openssl-rehash(1) or similar.

The -signkey option has been renamed to -key in OpenSSL 3.0, keeping the old name as an alias.

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

Since OpenSSL 3.2, generated certificates bear X.509 version 3, and key identifier extensions are included by default.

"},{"location":"man1/openssl-x509/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/openssl/","title":"openssl","text":""},{"location":"man1/openssl/#name","title":"NAME","text":"

openssl - OpenSSL command line program

"},{"location":"man1/openssl/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

openssl no-XXX [ options ]

openssl -help | -version

"},{"location":"man1/openssl/#description","title":"DESCRIPTION","text":"

OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) network protocols and related cryptography standards required by them.

The openssl program is a command line program for using the various cryptography functions of OpenSSL's crypto library from the shell. It can be used for

o  Creation and management of private keys, public keys and parameters\no  Public key cryptographic operations\no  Creation of X.509 certificates, CSRs and CRLs\no  Calculation of Message Digests and Message Authentication Codes\no  Encryption and Decryption with Ciphers\no  SSL/TLS Client and Server Tests\no  Handling of S/MIME signed or encrypted mail\no  Timestamp requests, generation and verification\n
"},{"location":"man1/openssl/#command-summary","title":"COMMAND SUMMARY","text":"

The openssl program provides a rich variety of commands (command in the \"SYNOPSIS\" above). Each command can have many options and argument parameters, shown above as options and parameters.

Detailed documentation and use cases for most standard subcommands are available (e.g., openssl-x509(1)). The subcommand openssl-list(1) may be used to list subcommands.

The command no-XXX tests whether a command of the specified name is available. If no command named XXX exists, it returns 0 (success) and prints no-XXX; otherwise it returns 1 and prints XXX. In both cases, the output goes to stdout and nothing is printed to stderr. Additional command line arguments are always ignored. Since for each cipher there is a command of the same name, this provides an easy way for shell scripts to test for the availability of ciphers in the openssl program. (no-XXX is not able to detect pseudo-commands such as quit, list, or no-XXX itself.)

"},{"location":"man1/openssl/#configuration-option","title":"Configuration Option","text":"

Many commands use an external configuration file for some or all of their arguments and have a -config option to specify that file. The default name of the file is openssl.cnf in the default certificate storage area, which can be determined from the openssl-version(1) command using the -d or -a option. The environment variable OPENSSL_CONF can be used to specify a different file location or to disable loading a configuration (using the empty string).

Among others, the configuration file can be used to load modules and to specify parameters for generating certificates and random numbers. See config(5) for details.

"},{"location":"man1/openssl/#standard-commands","title":"Standard Commands","text":""},{"location":"man1/openssl/#message-digest-commands","title":"Message Digest Commands","text":""},{"location":"man1/openssl/#encryption-decryption-and-encoding-commands","title":"Encryption, Decryption, and Encoding Commands","text":"

The following aliases provide convenient access to the most used encodings and ciphers.

Depending on how OpenSSL was configured and built, not all ciphers listed here may be present. See openssl-enc(1) for more information.

"},{"location":"man1/openssl/#options","title":"OPTIONS","text":"

Details of which options are available depend on the specific command. This section describes some common options with common behavior.

"},{"location":"man1/openssl/#program-options","title":"Program Options","text":"

These options can be specified without a command specified to get help or version information.

"},{"location":"man1/openssl/#common-options","title":"Common Options","text":""},{"location":"man1/openssl/#format-options","title":"Format Options","text":"

See openssl-format-options(1) for manual page.

"},{"location":"man1/openssl/#pass-phrase-options","title":"Pass Phrase Options","text":"

See the openssl-passphrase-options(1) manual page.

"},{"location":"man1/openssl/#random-state-options","title":"Random State Options","text":"

Prior to OpenSSL 1.1.1, it was common for applications to store information about the state of the random-number generator in a file that was loaded at startup and rewritten upon exit. On modern operating systems, this is generally no longer necessary as OpenSSL will seed itself from a trusted entropy source provided by the operating system. These flags are still supported for special platforms or circumstances that might require them.

It is generally an error to use the same seed file more than once and every use of -rand should be paired with -writerand.

"},{"location":"man1/openssl/#certificate-verification-options","title":"Certificate Verification Options","text":"

See the openssl-verification-options(1) manual page.

"},{"location":"man1/openssl/#name-format-options","title":"Name Format Options","text":"

See the openssl-namedisplay-options(1) manual page.

"},{"location":"man1/openssl/#tls-version-options","title":"TLS Version Options","text":"

Several commands use SSL, TLS, or DTLS. By default, the commands use TLS and clients will offer the lowest and highest protocol version they support, and servers will pick the highest version that the client offers that is also supported by the server.

The options below can be used to limit which protocol versions are used, and whether TCP (SSL and TLS) or UDP (DTLS) is used. Note that not all protocols and flags may be available, depending on how OpenSSL was built.

"},{"location":"man1/openssl/#engine-options","title":"Engine Options","text":"

Options specifying keys, like -key and similar, can use the generic OpenSSL engine key loading URI scheme org.openssl.engine: to retrieve private keys and public keys. The URI syntax is as follows, in simplified form:

org.openssl.engine:{engineid}:{keyid}\n

Where {engineid} is the identity/name of the engine, and {keyid} is a key identifier that's acceptable by that engine. For example, when using an engine that interfaces against a PKCS#11 implementation, the generic key URI would be something like this (this happens to be an example for the PKCS#11 engine that's part of OpenSC):

-key org.openssl.engine:pkcs11:label_some-private-key\n

As a third possibility, for engines and providers that have implemented their own OSSL_STORE_LOADER(3), org.openssl.engine: should not be necessary. For a PKCS#11 implementation that has implemented such a loader, the PKCS#11 URI as defined in RFC 7512 should be possible to use directly:

-key pkcs11:object=some-private-key;pin-value=1234\n
"},{"location":"man1/openssl/#provider-options","title":"Provider Options","text":""},{"location":"man1/openssl/#environment","title":"ENVIRONMENT","text":"

The OpenSSL libraries can take some configuration parameters from the environment.

For information about all environment variables used by the OpenSSL libraries, such as OPENSSL_CONF, OPENSSL_MODULES, and OPENSSL_TRACE, see openssl-env(7).

For information about the use of environment variables in configuration, see \"ENVIRONMENT\" in config(5).

For information about specific commands, see openssl-engine(1), openssl-rehash(1), and tsget(1).

For information about querying or specifying CPU architecture flags, see OPENSSL_ia32cap(3), OPENSSL_s390xcap(3) and OPENSSL_riscvcap(3).

"},{"location":"man1/openssl/#see-also","title":"SEE ALSO","text":"

openssl-asn1parse(1), openssl-ca(1), openssl-ciphers(1), openssl-cms(1), openssl-crl(1), openssl-crl2pkcs7(1), openssl-dgst(1), openssl-dhparam(1), openssl-dsa(1), openssl-dsaparam(1), openssl-ec(1), openssl-ecparam(1), openssl-enc(1), openssl-engine(1), openssl-errstr(1), openssl-gendsa(1), openssl-genpkey(1), openssl-genrsa(1), openssl-kdf(1), openssl-list(1), openssl-mac(1), openssl-nseq(1), openssl-ocsp(1), openssl-passwd(1), openssl-pkcs12(1), openssl-pkcs7(1), openssl-pkcs8(1), openssl-pkey(1), openssl-pkeyparam(1), openssl-pkeyutl(1), openssl-prime(1), openssl-rand(1), openssl-rehash(1), openssl-req(1), openssl-rsa(1), openssl-rsautl(1), openssl-s_client(1), openssl-s_server(1), openssl-s_time(1), openssl-sess_id(1), openssl-smime(1), openssl-speed(1), openssl-spkac(1), openssl-srp(1), openssl-storeutl(1), openssl-ts(1), openssl-verify(1), openssl-version(1), openssl-x509(1), config(5), crypto(7), openssl-env(7). ssl(7), x509v3_config(5)

"},{"location":"man1/openssl/#history","title":"HISTORY","text":"

The list -XXX-algorithms options were added in OpenSSL 1.0.0; For notes on the availability of other commands, see their individual manual pages.

The -issuer_checks option is deprecated as of OpenSSL 1.1.0 and is silently ignored.

The -xcertform and -xkeyform options are obsolete since OpenSSL 3.0 and have no effect.

The interactive mode, which could be invoked by running openssl with no further arguments, was removed in OpenSSL 3.0, and running that program with no arguments is now equivalent to openssl help.

"},{"location":"man1/openssl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man1/tsget/","title":"tsget","text":""},{"location":"man1/tsget/#name","title":"NAME","text":"

tsget - Time Stamping HTTP/HTTPS client

"},{"location":"man1/tsget/#synopsis","title":"SYNOPSIS","text":"

tsget -h server_url [-e extension] [-o output] [-v] [-d] [-k private_key.pem] [-p key_password] [-c client_cert.pem] [-C CA_certs.pem] [-P CA_path] [-r files] [-g EGD_socket] [request ...]

"},{"location":"man1/tsget/#description","title":"DESCRIPTION","text":"

This command can be used for sending a timestamp request, as specified in RFC 3161, to a timestamp server over HTTP or HTTPS and storing the timestamp response in a file. It cannot be used for creating the requests and verifying responses, you have to use openssl-ts(1) to do that. This command can send several requests to the server without closing the TCP connection if more than one requests are specified on the command line.

This command sends the following HTTP request for each timestamp request:

    POST url HTTP/1.1\n    User-Agent: OpenTSA tsget.pl/<version>\n    Host: <host>:<port>\n    Pragma: no-cache\n    Content-Type: application/timestamp-query\n    Accept: application/timestamp-reply\n    Content-Length: length of body\n\n    ...binary request specified by the user...\n

It expects a response of type application/timestamp-reply, which is written to a file without any interpretation.

"},{"location":"man1/tsget/#options","title":"OPTIONS","text":""},{"location":"man1/tsget/#environment-variables","title":"ENVIRONMENT VARIABLES","text":"

The TSGET environment variable can optionally contain default arguments. The content of this variable is added to the list of command line arguments.

"},{"location":"man1/tsget/#examples","title":"EXAMPLES","text":"

The examples below presume that file1.tsq and file2.tsq contain valid timestamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests and at port 8443 for HTTPS requests, the TSA service is available at the /tsa absolute path.

Get a timestamp response for file1.tsq over HTTP, output is written to file1.tsr:

tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq\n

Get a timestamp response for file1.tsq and file2.tsq over HTTP showing progress, output is written to file1.reply and file2.reply respectively:

tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \\\n      file1.tsq file2.tsq\n

Create a timestamp request, write it to file3.tsq, send it to the server and write the response to file3.tsr:

openssl ts -query -data file3.txt -cert | tee file3.tsq \\\n      | tsget -h http://tsa.opentsa.org:8080/tsa \\\n      -o file3.tsr\n

Get a timestamp response for file1.tsq over HTTPS without client authentication:

tsget -h https://tsa.opentsa.org:8443/tsa \\\n      -C cacerts.pem file1.tsq\n

Get a timestamp response for file1.tsq over HTTPS with certificate-based client authentication (it will ask for the passphrase if client_key.pem is protected):

tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \\\n      -k client_key.pem -c client_cert.pem file1.tsq\n

You can shorten the previous command line if you make use of the TSGET environment variable. The following commands do the same as the previous example:

TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \\\n      -k client_key.pem -c client_cert.pem'\nexport TSGET\ntsget file1.tsq\n
"},{"location":"man1/tsget/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ts(1), WWW::Curl::Easy, https://www.rfc-editor.org/rfc/rfc3161.html

"},{"location":"man1/tsget/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ADMISSIONS/","title":"ADMISSIONS","text":""},{"location":"man3/ADMISSIONS/#name","title":"NAME","text":"

ADMISSIONS, ADMISSIONS_get0_admissionAuthority, ADMISSIONS_get0_namingAuthority, ADMISSIONS_get0_professionInfos, ADMISSIONS_set0_admissionAuthority, ADMISSIONS_set0_namingAuthority, ADMISSIONS_set0_professionInfos, ADMISSION_SYNTAX, ADMISSION_SYNTAX_get0_admissionAuthority, ADMISSION_SYNTAX_get0_contentsOfAdmissions, ADMISSION_SYNTAX_set0_admissionAuthority, ADMISSION_SYNTAX_set0_contentsOfAdmissions, NAMING_AUTHORITY, NAMING_AUTHORITY_get0_authorityId, NAMING_AUTHORITY_get0_authorityURL, NAMING_AUTHORITY_get0_authorityText, NAMING_AUTHORITY_set0_authorityId, NAMING_AUTHORITY_set0_authorityURL, NAMING_AUTHORITY_set0_authorityText, PROFESSION_INFO, PROFESSION_INFOS, PROFESSION_INFO_get0_addProfessionInfo, PROFESSION_INFO_get0_namingAuthority, PROFESSION_INFO_get0_professionItems, PROFESSION_INFO_get0_professionOIDs, PROFESSION_INFO_get0_registrationNumber, PROFESSION_INFO_set0_addProfessionInfo, PROFESSION_INFO_set0_namingAuthority, PROFESSION_INFO_set0_professionItems, PROFESSION_INFO_set0_professionOIDs, PROFESSION_INFO_set0_registrationNumber - Accessors and settors for ADMISSION_SYNTAX

"},{"location":"man3/ADMISSIONS/#synopsis","title":"SYNOPSIS","text":"
typedef struct NamingAuthority_st NAMING_AUTHORITY;\ntypedef struct ProfessionInfo_st PROFESSION_INFO;\ntypedef STACK_OF(PROFESSION_INFO) PROFESSION_INFOS;\ntypedef struct Admissions_st ADMISSIONS;\ntypedef struct AdmissionSyntax_st ADMISSION_SYNTAX;\n\nconst ASN1_OBJECT *NAMING_AUTHORITY_get0_authorityId(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityId(NAMING_AUTHORITY *n,\n    ASN1_OBJECT* namingAuthorityId);\nconst ASN1_IA5STRING *NAMING_AUTHORITY_get0_authorityURL(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityURL(NAMING_AUTHORITY *n,\n    ASN1_IA5STRING* namingAuthorityUrl);\nconst ASN1_STRING *NAMING_AUTHORITY_get0_authorityText(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityText(NAMING_AUTHORITY *n,\n    ASN1_STRING* namingAuthorityText);\n\nconst GENERAL_NAME *ADMISSION_SYNTAX_get0_admissionAuthority(\n    const ADMISSION_SYNTAX *as);\nvoid ADMISSION_SYNTAX_set0_admissionAuthority(\n    ADMISSION_SYNTAX *as, GENERAL_NAME *aa);\nconst STACK_OF(ADMISSIONS) *ADMISSION_SYNTAX_get0_contentsOfAdmissions(\n    const ADMISSION_SYNTAX *as);\nvoid ADMISSION_SYNTAX_set0_contentsOfAdmissions(\n    ADMISSION_SYNTAX *as, STACK_OF(ADMISSIONS) *a);\n\nconst GENERAL_NAME *ADMISSIONS_get0_admissionAuthority(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_admissionAuthority(ADMISSIONS *a, GENERAL_NAME *aa);\nconst NAMING_AUTHORITY *ADMISSIONS_get0_namingAuthority(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_namingAuthority(ADMISSIONS *a, NAMING_AUTHORITY *na);\nconst PROFESSION_INFOS *ADMISSIONS_get0_professionInfos(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_professionInfos(ADMISSIONS *a, PROFESSION_INFOS *pi);\n\nconst ASN1_OCTET_STRING *PROFESSION_INFO_get0_addProfessionInfo(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_addProfessionInfo(\n    PROFESSION_INFO *pi, ASN1_OCTET_STRING *aos);\nconst NAMING_AUTHORITY *PROFESSION_INFO_get0_namingAuthority(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_namingAuthority(\n    PROFESSION_INFO *pi, NAMING_AUTHORITY *na);\nconst STACK_OF(ASN1_STRING) *PROFESSION_INFO_get0_professionItems(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_professionItems(\n    PROFESSION_INFO *pi, STACK_OF(ASN1_STRING) *as);\nconst STACK_OF(ASN1_OBJECT) *PROFESSION_INFO_get0_professionOIDs(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_professionOIDs(\n    PROFESSION_INFO *pi, STACK_OF(ASN1_OBJECT) *po);\nconst ASN1_PRINTABLESTRING *PROFESSION_INFO_get0_registrationNumber(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_registrationNumber(\n    PROFESSION_INFO *pi, ASN1_PRINTABLESTRING *rn);\n
"},{"location":"man3/ADMISSIONS/#description","title":"DESCRIPTION","text":"

The PROFESSION_INFOS, ADMISSION_SYNTAX, ADMISSIONS, and PROFESSION_INFO types are opaque structures representing the analogous types defined in the Common PKI Specification published by https://www.t7ev.org. Knowledge of those structures and their semantics is assumed.

The conventional routines to convert between DER and the local format are described in d2i_X509(3). The conventional routines to allocate and free the types are defined in X509_dup(3).

The PROFESSION_INFOS type is a stack of PROFESSION_INFO; see DEFINE_STACK_OF(3) for details.

The NAMING_AUTHORITY type has an authority ID and URL, and text fields. The NAMING_AUTHORITY_get0_authorityId(), NAMING_AUTHORITY_get0_get0_authorityURL(), and NAMING_AUTHORITY_get0_get0_authorityText(), functions return pointers to those values within the object. The NAMING_AUTHORITY_set0_authorityId(), NAMING_AUTHORITY_set0_get0_authorityURL(), and NAMING_AUTHORITY_set0_get0_authorityText(), functions free any existing value and set the pointer to the specified value.

The ADMISSION_SYNTAX type has an authority name and a stack of ADMISSION objects. The ADMISSION_SYNTAX_get0_admissionAuthority() and ADMISSION_SYNTAX_get0_contentsOfAdmissions() functions return pointers to those values within the object. The ADMISSION_SYNTAX_set0_admissionAuthority() and ADMISSION_SYNTAX_set0_contentsOfAdmissions() functions free any existing value and set the pointer to the specified value.

The ADMISSION type has an authority name, authority object, and a stack of PROFESSION_INFO items. The ADMISSIONS_get0_admissionAuthority(), ADMISSIONS_get0_namingAuthority(), and ADMISSIONS_get0_professionInfos() functions return pointers to those values within the object. The ADMISSIONS_set0_admissionAuthority(), ADMISSIONS_set0_namingAuthority(), and ADMISSIONS_set0_professionInfos() functions free any existing value and set the pointer to the specified value.

The PROFESSION_INFO type has a name authority, stacks of profession Items and OIDs, a registration number, and additional profession info. The functions PROFESSION_INFO_get0_addProfessionInfo(), PROFESSION_INFO_get0_namingAuthority(), PROFESSION_INFO_get0_professionItems(), PROFESSION_INFO_get0_professionOIDs(), and PROFESSION_INFO_get0_registrationNumber() functions return pointers to those values within the object. The PROFESSION_INFO_set0_addProfessionInfo(), PROFESSION_INFO_set0_namingAuthority(), PROFESSION_INFO_set0_professionItems(), PROFESSION_INFO_set0_professionOIDs(), and PROFESSION_INFO_set0_registrationNumber() functions free any existing value and set the pointer to the specified value.

"},{"location":"man3/ADMISSIONS/#return-values","title":"RETURN VALUES","text":"

Described above. Note that all of the get0 functions return a pointer to the internal data structure and must not be freed.

"},{"location":"man3/ADMISSIONS/#see-also","title":"SEE ALSO","text":"

X509_dup(3), d2i_X509(3),

"},{"location":"man3/ADMISSIONS/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2018 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.

"},{"location":"man3/ASN1_EXTERN_FUNCS/","title":"ASN1_EXTERN_FUNCS","text":""},{"location":"man3/ASN1_EXTERN_FUNCS/#name","title":"NAME","text":"

ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func, ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func, IMPLEMENT_EXTERN_ASN1 - ASN.1 external function support

"},{"location":"man3/ASN1_EXTERN_FUNCS/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1t.h>\n\ntypedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,\n                        const ASN1_ITEM *it, int tag, int aclass, char opt,\n                        ASN1_TLC *ctx);\ntypedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,\n                           const ASN1_ITEM *it, int tag, int aclass, char opt,\n                           ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,\n                           const char *propq);\ntypedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,\n                        const ASN1_ITEM *it, int tag, int aclass);\ntypedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);\ntypedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,\n                                OSSL_LIB_CTX *libctx, const char *propq);\ntypedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);\ntypedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,\n                               int indent, const char *fname,\n                               const ASN1_PCTX *pctx);\n\nstruct ASN1_EXTERN_FUNCS_st {\n   void *app_data;\n   ASN1_ex_new_func *asn1_ex_new;\n   ASN1_ex_free_func *asn1_ex_free;\n   ASN1_ex_free_func *asn1_ex_clear;\n   ASN1_ex_d2i *asn1_ex_d2i;\n   ASN1_ex_i2d *asn1_ex_i2d;\n   ASN1_ex_print_func *asn1_ex_print;\n   ASN1_ex_new_ex_func *asn1_ex_new_ex;\n   ASN1_ex_d2i_ex *asn1_ex_d2i_ex;\n};\ntypedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;\n\n#define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)\n
"},{"location":"man3/ASN1_EXTERN_FUNCS/#description","title":"DESCRIPTION","text":"

ASN.1 data structures templates are typically defined in OpenSSL using a series of macros such as ASN1_SEQUENCE(), ASN1_SEQUENCE_END() and so on. Instead templates can also be defined based entirely on external functions. These external functions are called to perform operations such as creating a new ASN1_VALUE or converting an ASN1_VALUE to or from DER encoding.

The macro IMPLEMENT_EXTERN_ASN1() can be used to create such an externally defined structure. The name of the structure should be supplied in the sname parameter. The tag for the structure (e.g. typically V_ASN1_SEQUENCE) should be supplied in the tag parameter. Finally a pointer to an ASN1_EXTERN_FUNCS structure should be supplied in the fptrs parameter.

The ASN1_EXTERN_FUNCS structure has the following entries.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#return-values","title":"RETURN VALUES","text":"

Return values for the various callbacks are as described above.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#see-also","title":"SEE ALSO","text":"

ASN1_item_new_ex(3)

"},{"location":"man3/ASN1_EXTERN_FUNCS/#history","title":"HISTORY","text":"

The asn1_ex_new_ex and asn1_ex_d2i_ex callbacks were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/ASN1_INTEGER_get_int64/","title":"ASN1_INTEGER_get_int64","text":""},{"location":"man3/ASN1_INTEGER_get_int64/#name","title":"NAME","text":"

ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN - ASN.1 INTEGER and ENUMERATED utilities

"},{"location":"man3/ASN1_INTEGER_get_int64/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);\nlong ASN1_INTEGER_get(const ASN1_INTEGER *a);\n\nint ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);\nint ASN1_INTEGER_set(ASN1_INTEGER *a, long v);\n\nint ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);\nint ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);\n\nASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);\nBIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);\n\nint ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);\nlong ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);\n\nint ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);\nint ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);\n\nASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai);\nBIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn);\n
"},{"location":"man3/ASN1_INTEGER_get_int64/#description","title":"DESCRIPTION","text":"

These functions convert to and from ASN1_INTEGER and ASN1_ENUMERATED structures.

ASN1_INTEGER_get_int64() converts an ASN1_INTEGER into an int64_t type If successful it returns 1 and sets *pr to the value of a. If it fails (due to invalid type or the value being too big to fit into an int64_t type) it returns 0.

ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it converts to a uint64_t type and an error is returned if the passed integer is negative.

ASN1_INTEGER_get() also returns the value of a but it returns 0 if a is NULL and -1 on error (which is ambiguous because -1 is a legitimate value for an ASN1_INTEGER). New applications should use ASN1_INTEGER_get_int64() instead.

ASN1_INTEGER_set_int64() sets the value of ASN1_INTEGER a to the int64_t value r.

ASN1_INTEGER_set_uint64() sets the value of ASN1_INTEGER a to the uint64_t value r.

ASN1_INTEGER_set() sets the value of ASN1_INTEGER a to the long value v.

BN_to_ASN1_INTEGER() converts BIGNUM bn to an ASN1_INTEGER. If ai is NULL a new ASN1_INTEGER structure is returned. If ai is not NULL then the existing structure will be used instead.

ASN1_INTEGER_to_BN() converts ASN1_INTEGER ai into a BIGNUM. If bn is NULL a new BIGNUM structure is returned. If bn is not NULL then the existing structure will be used instead.

ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(), ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN() behave in an identical way to their ASN1_INTEGER counterparts except they operate on an ASN1_ENUMERATED value.

ASN1_ENUMERATED_get() returns the value of a in a similar way to ASN1_INTEGER_get() but it returns 0xffffffffL if the value of a will not fit in a long type. New applications should use ASN1_ENUMERATED_get_int64() instead.

"},{"location":"man3/ASN1_INTEGER_get_int64/#notes","title":"NOTES","text":"

In general an ASN1_INTEGER or ASN1_ENUMERATED type can contain an integer of almost arbitrary size and so cannot always be represented by a C int64_t type. However, in many cases (for example version numbers) they represent small integers which can be more easily manipulated if converted to an appropriate C integer type.

"},{"location":"man3/ASN1_INTEGER_get_int64/#bugs","title":"BUGS","text":"

The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() mean these functions should be avoided if possible. They are retained for compatibility. Normally the ambiguous return values are not legitimate values for the fields they represent.

"},{"location":"man3/ASN1_INTEGER_get_int64/#return-values","title":"RETURN VALUES","text":"

ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only fail if a memory allocation error occurs.

ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success and 0 for failure. They will fail if the passed type is incorrect (this will only happen if there is a programming error) or if the value exceeds the range of an int64_t type.

BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an ASN1_INTEGER or ASN1_ENUMERATED structure respectively or NULL if an error occurs. They will only fail due to a memory allocation error.

ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a BIGNUM structure of NULL if an error occurs. They can fail if the passed type is incorrect (due to programming error) or due to a memory allocation failure.

"},{"location":"man3/ASN1_INTEGER_get_int64/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_INTEGER_get_int64/#history","title":"HISTORY","text":"

ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(), ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64() were added in OpenSSL 1.1.0.

"},{"location":"man3/ASN1_INTEGER_get_int64/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ASN1_INTEGER_new/","title":"ASN1_INTEGER_new","text":""},{"location":"man3/ASN1_INTEGER_new/#name","title":"NAME","text":"

ASN1_INTEGER_new, ASN1_INTEGER_free - ASN1_INTEGER allocation functions

"},{"location":"man3/ASN1_INTEGER_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_INTEGER *ASN1_INTEGER_new(void);\nvoid ASN1_INTEGER_free(ASN1_INTEGER *a);\n
"},{"location":"man3/ASN1_INTEGER_new/#description","title":"DESCRIPTION","text":"

ASN1_INTEGER_new() returns an allocated ASN1_INTEGER structure.

ASN1_INTEGER_free() frees up a single ASN1_INTEGER object. If the argument is NULL, nothing is done.

ASN1_INTEGER structure representing the ASN.1 INTEGER type

"},{"location":"man3/ASN1_INTEGER_new/#return-values","title":"RETURN VALUES","text":"

ASN1_INTEGER_new() return a valid ASN1_INTEGER structure or NULL if an error occurred.

ASN1_INTEGER_free() does not return a value.

"},{"location":"man3/ASN1_INTEGER_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_INTEGER_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2024 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.

"},{"location":"man3/ASN1_ITEM_lookup/","title":"ASN1_ITEM_lookup","text":""},{"location":"man3/ASN1_ITEM_lookup/#name","title":"NAME","text":"

ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures

"},{"location":"man3/ASN1_ITEM_lookup/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nconst ASN1_ITEM *ASN1_ITEM_lookup(const char *name);\nconst ASN1_ITEM *ASN1_ITEM_get(size_t i);\n
"},{"location":"man3/ASN1_ITEM_lookup/#description","title":"DESCRIPTION","text":"

ASN1_ITEM_lookup() returns the ASN1_ITEM named name.

ASN1_ITEM_get() returns the ASN1_ITEM with index i. This function returns NULL if the index i is out of range.

"},{"location":"man3/ASN1_ITEM_lookup/#return-values","title":"RETURN VALUES","text":"

ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid ASN1_ITEM structure or NULL if an error occurred.

"},{"location":"man3/ASN1_ITEM_lookup/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_ITEM_lookup/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/ASN1_OBJECT_new/","title":"ASN1_OBJECT_new","text":""},{"location":"man3/ASN1_OBJECT_new/#name","title":"NAME","text":"

ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions

"},{"location":"man3/ASN1_OBJECT_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_OBJECT *ASN1_OBJECT_new(void);\nvoid ASN1_OBJECT_free(ASN1_OBJECT *a);\n
"},{"location":"man3/ASN1_OBJECT_new/#description","title":"DESCRIPTION","text":"

The ASN1_OBJECT allocation routines, allocate and free an ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.

ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.

ASN1_OBJECT_free() frees up the ASN1_OBJECT structure a. If a is NULL, nothing is done.

"},{"location":"man3/ASN1_OBJECT_new/#notes","title":"NOTES","text":"

Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it is almost never used in applications. The ASN1 object utility functions such as OBJ_nid2obj() are used instead.

"},{"location":"man3/ASN1_OBJECT_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, ASN1_OBJECT_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

ASN1_OBJECT_free() returns no value.

"},{"location":"man3/ASN1_OBJECT_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), d2i_ASN1_OBJECT(3)

"},{"location":"man3/ASN1_OBJECT_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2016 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.

"},{"location":"man3/ASN1_STRING_TABLE_add/","title":"ASN1_STRING_TABLE_add","text":""},{"location":"man3/ASN1_STRING_TABLE_add/#name","title":"NAME","text":"

ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get, ASN1_STRING_TABLE_cleanup - ASN1_STRING_TABLE manipulation functions

"},{"location":"man3/ASN1_STRING_TABLE_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\ntypedef struct asn1_string_table_st ASN1_STRING_TABLE;\n\nint ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,\n                          unsigned long mask, unsigned long flags);\nASN1_STRING_TABLE *ASN1_STRING_TABLE_get(int nid);\nvoid ASN1_STRING_TABLE_cleanup(void);\n
"},{"location":"man3/ASN1_STRING_TABLE_add/#description","title":"DESCRIPTION","text":""},{"location":"man3/ASN1_STRING_TABLE_add/#types","title":"Types","text":"

ASN1_STRING_TABLE is a table which holds string information (basically minimum size, maximum size, type and etc) for a NID object.

"},{"location":"man3/ASN1_STRING_TABLE_add/#functions","title":"Functions","text":"

ASN1_STRING_TABLE_add() adds a new ASN1_STRING_TABLE item into the local ASN1 string table based on the nid along with other parameters.

If the item is already in the table, fields of ASN1_STRING_TABLE are updated (depending on the values of those parameters, e.g., minsize and maxsize >= 0, mask and flags != 0). If the nid is standard, a copy of the standard ASN1_STRING_TABLE is created and updated with other parameters.

ASN1_STRING_TABLE_get() searches for an ASN1_STRING_TABLE item based on nid. It will search the local table first, then the standard one.

ASN1_STRING_TABLE_cleanup() frees all ASN1_STRING_TABLE items added by ASN1_STRING_TABLE_add().

"},{"location":"man3/ASN1_STRING_TABLE_add/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_TABLE_add() returns 1 on success, 0 if an error occurred.

ASN1_STRING_TABLE_get() returns a valid ASN1_STRING_TABLE structure or NULL if nothing is found.

ASN1_STRING_TABLE_cleanup() does not return a value.

"},{"location":"man3/ASN1_STRING_TABLE_add/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_TABLE_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ASN1_STRING_length/","title":"ASN1_STRING_length","text":""},{"location":"man3/ASN1_STRING_length/#name","title":"NAME","text":"

ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, ASN1_STRING_to_UTF8 - ASN1_STRING utility functions

"},{"location":"man3/ASN1_STRING_length/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_STRING_length(ASN1_STRING *x);\nconst unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x);\nunsigned char *ASN1_STRING_data(ASN1_STRING *x);\n\nASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a);\n\nint ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);\n\nint ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);\n\nint ASN1_STRING_type(const ASN1_STRING *x);\n\nint ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);\n
"},{"location":"man3/ASN1_STRING_length/#description","title":"DESCRIPTION","text":"

These functions allow an ASN1_STRING structure to be manipulated.

ASN1_STRING_length() returns the length of the content of x. x MUST NOT be NULL.

ASN1_STRING_get0_data() returns an internal pointer to the data of x. Since this is an internal pointer it should not be freed or modified in any way. x MUST NOT be NULL.

ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the returned value is not constant. This function is deprecated: applications should use ASN1_STRING_get0_data() instead.

ASN1_STRING_dup() returns a copy of the structure a.

ASN1_STRING_cmp() compares a and b returning 0 if the two are identical. The string types and content are compared.

ASN1_STRING_set() sets the data of string str to the buffer data or length len. The supplied data is copied. If len is -1 then the length is determined by strlen(data).

ASN1_STRING_type() returns the type of x, using standard constants such as V_ASN1_OCTET_STRING.

ASN1_STRING_to_UTF8() converts the string in to UTF8 format, the converted data is allocated in a buffer in *out. The length of out is returned or a negative error code. The buffer *out should be freed using OPENSSL_free().

"},{"location":"man3/ASN1_STRING_length/#notes","title":"NOTES","text":"

Almost all ASN1 types in OpenSSL are represented as an ASN1_STRING structure. Other types such as ASN1_OCTET_STRING are simply typedef'ed to ASN1_STRING and the functions call the ASN1_STRING equivalents. ASN1_STRING is also used for some CHOICE types which consist entirely of primitive string types such as DirectoryString and Time.

These functions should not be used to examine or modify ASN1_INTEGER or ASN1_ENUMERATED types: the relevant INTEGER or ENUMERATED utility functions should be used instead.

In general it cannot be assumed that the data returned by ASN1_STRING_data() is null terminated or does not contain embedded nulls. The actual format of the data will depend on the actual string type itself: for example for an IA5String the data will be ASCII, for a BMPString two bytes per character in big endian format, and for a UTF8String it will be in UTF8 format.

Similar care should be take to ensure the data is in the correct format when calling ASN1_STRING_set().

"},{"location":"man3/ASN1_STRING_length/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_length() returns the length of the content of x.

ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to the data of x.

ASN1_STRING_dup() returns a valid ASN1_STRING structure or NULL if an error occurred.

ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0, according to whether a is greater than, equal to, or less than b.

ASN1_STRING_set() returns 1 on success or 0 on error.

ASN1_STRING_type() returns the type of x.

ASN1_STRING_to_UTF8() returns the number of bytes in output string out or a negative value if an error occurred.

"},{"location":"man3/ASN1_STRING_length/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_length/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ASN1_STRING_new/","title":"ASN1_STRING_new","text":""},{"location":"man3/ASN1_STRING_new/#name","title":"NAME","text":"

ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - ASN1_STRING allocation functions

"},{"location":"man3/ASN1_STRING_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_STRING *ASN1_STRING_new(void);\nASN1_STRING *ASN1_STRING_type_new(int type);\nvoid ASN1_STRING_free(ASN1_STRING *a);\n
"},{"location":"man3/ASN1_STRING_new/#description","title":"DESCRIPTION","text":"

ASN1_STRING_new() returns an allocated ASN1_STRING structure. Its type is undefined.

ASN1_STRING_type_new() returns an allocated ASN1_STRING structure of type type.

ASN1_STRING_free() frees up a. If a is NULL nothing is done.

"},{"location":"man3/ASN1_STRING_new/#notes","title":"NOTES","text":"

Other string types call the ASN1_STRING functions. For example ASN1_OCTET_STRING_new() calls ASN1_STRING_type_new(V_ASN1_OCTET_STRING).

"},{"location":"man3/ASN1_STRING_new/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_new() and ASN1_STRING_type_new() return a valid ASN1_STRING structure or NULL if an error occurred.

ASN1_STRING_free() does not return a value.

"},{"location":"man3/ASN1_STRING_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2023 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.

"},{"location":"man3/ASN1_STRING_print_ex/","title":"ASN1_STRING_print_ex","text":""},{"location":"man3/ASN1_STRING_print_ex/#name","title":"NAME","text":"

ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines

"},{"location":"man3/ASN1_STRING_print_ex/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);\nint ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);\nint ASN1_STRING_print(BIO *out, const ASN1_STRING *str);\n\nconst char *ASN1_tag2str(int tag);\n
"},{"location":"man3/ASN1_STRING_print_ex/#description","title":"DESCRIPTION","text":"

These functions output an ASN1_STRING structure. ASN1_STRING is used to represent all the ASN1 string types.

ASN1_STRING_print_ex() outputs str to out, the format is determined by the options flags. ASN1_STRING_print_ex_fp() is identical except it outputs to fp instead.

ASN1_STRING_print() prints str to out but using a different format to ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF) with '.'.

ASN1_tag2str() returns a human-readable name of the specified ASN.1 tag.

"},{"location":"man3/ASN1_STRING_print_ex/#notes","title":"NOTES","text":"

ASN1_STRING_print() is a deprecated function which should be avoided; use ASN1_STRING_print_ex() instead.

Although there are a large number of options frequently ASN1_STRFLGS_RFC2253 is suitable, or on UTF8 terminals ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB.

The complete set of supported options for flags is listed below.

Various characters can be escaped. If ASN1_STRFLGS_ESC_2253 is set the characters determined by RFC2253 are escaped. If ASN1_STRFLGS_ESC_CTRL is set control characters are escaped. If ASN1_STRFLGS_ESC_MSB is set characters with the MSB set are escaped: this option should not be used if the terminal correctly interprets UTF8 sequences.

Escaping takes several forms.

If the character being escaped is a 16 bit character then the form \"\\UXXXX\" is used using exactly four characters for the hex representation. If it is 32 bits then \"\\WXXXXXXXX\" is used using eight characters of its hex representation. These forms will only be used if UTF8 conversion is not set (see below).

Printable characters are normally escaped using the backslash '\\' character. If ASN1_STRFLGS_ESC_QUOTE is set then the whole string is instead surrounded by double quote characters: this is arguably more readable than the backslash notation. Other characters use the \"\\XX\" using exactly two characters of the hex representation.

If ASN1_STRFLGS_UTF8_CONVERT is set then characters are converted to UTF8 format first. If the terminal supports the display of UTF8 sequences then this option will correctly display multi byte characters.

If ASN1_STRFLGS_IGNORE_TYPE is set then the string type is not interpreted at all: everything is assumed to be one byte per character. This is primarily for debugging purposes and can result in confusing output in multi character strings.

If ASN1_STRFLGS_SHOW_TYPE is set then the string type itself is printed out before its value (for example \"BMPSTRING\"), this actually uses ASN1_tag2str().

The content of a string instead of being interpreted can be \"dumped\": this just outputs the value of the string using the form #XXXX using hex format for each octet.

If ASN1_STRFLGS_DUMP_ALL is set then any type is dumped.

Normally non character string types (such as OCTET STRING) are assumed to be one byte per character, if ASN1_STRFLGS_DUMP_UNKNOWN is set then they will be dumped instead.

When a type is dumped normally just the content octets are printed, if ASN1_STRFLGS_DUMP_DER is set then the complete encoding is dumped instead (including tag and length octets).

ASN1_STRFLGS_RFC2253 includes all the flags required by RFC2253. It is equivalent to: ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER

"},{"location":"man3/ASN1_STRING_print_ex/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_print_ex() and ASN1_STRING_print_ex_fp() return the number of characters written or -1 if an error occurred.

ASN1_STRING_print() returns 1 on success or 0 on error.

ASN1_tag2str() returns a human-readable name of the specified ASN.1 tag.

"},{"location":"man3/ASN1_STRING_print_ex/#see-also","title":"SEE ALSO","text":"

X509_NAME_print_ex(3), ASN1_tag2str(3)

"},{"location":"man3/ASN1_STRING_print_ex/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2018 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.

"},{"location":"man3/ASN1_TIME_set/","title":"ASN1_TIME_set","text":""},{"location":"man3/ASN1_TIME_set/#name","title":"NAME","text":"

ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, ASN1_TIME_set_string_X509, ASN1_TIME_normalize, ASN1_TIME_to_tm, ASN1_TIME_print, ASN1_TIME_print_ex, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, ASN1_TIME_diff, ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, ASN1_TIME_compare, ASN1_TIME_to_generalizedtime, ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup - ASN.1 Time functions

"},{"location":"man3/ASN1_TIME_set/#synopsis","title":"SYNOPSIS","text":"
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);\nASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,\n                                               time_t t);\n\nASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,\n                         long offset_sec);\nASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,\n                               int offset_day, long offset_sec);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,\n                                               time_t t, int offset_day,\n                                               long offset_sec);\n\nint ASN1_TIME_set_string(ASN1_TIME *s, const char *str);\nint ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);\nint ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);\nint ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,\n                                    const char *str);\n\nint ASN1_TIME_normalize(ASN1_TIME *s);\n\nint ASN1_TIME_check(const ASN1_TIME *t);\nint ASN1_UTCTIME_check(const ASN1_UTCTIME *t);\nint ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);\n\nint ASN1_TIME_print(BIO *b, const ASN1_TIME *s);\nint ASN1_TIME_print_ex(BIO *bp, const ASN1_TIME *tm, unsigned long flags);\nint ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);\nint ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);\n\nint ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);\nint ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,\n                   const ASN1_TIME *to);\n\nint ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);\nint ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);\n\nint ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);\n\nASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,\n                                                   ASN1_GENERALIZEDTIME **out);\n\nASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t);\nASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t);\n
"},{"location":"man3/ASN1_TIME_set/#description","title":"DESCRIPTION","text":"

The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set() functions set the structure s to the time represented by the time_t value t. If s is NULL a new time structure is allocated and returned.

The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj() functions set the time structure s to the time represented by the time offset_day and offset_sec after the time_t value t. The values of offset_day or offset_sec can be negative to set a time before t. The offset_sec value can also exceed the number of seconds in a day. If s is NULL a new structure is allocated and returned.

The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and ASN1_GENERALIZEDTIME_set_string() functions set the time structure s to the time represented by string str which must be in appropriate ASN.1 time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If s is NULL this function performs a format check on str only. The string str is copied into s.

ASN1_TIME_set_string_X509() sets ASN1_TIME structure s to the time represented by string str which must be in appropriate time format that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format are not allowed. If s is NULL this function performs a format check on str only.

The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or ASN1_UTCTIME into a time value that can be used in a certificate. It should be used after the ASN1_TIME_set_string() functions and before ASN1_TIME_print() functions to get consistent (i.e. GMT) results.

The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check() functions check the syntax of the time structure s.

The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() functions print the time structure s to BIO b in human readable format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example \"Feb 3 00:55:52 2015 GMT\", which does not include a newline. If the time structure has invalid format it prints out \"Bad time value\" and returns an error. The output for generalized time may include a fractional part following the second.

ASN1_TIME_print_ex() provides flags to specify the output format of the datetime. This can be either ASN1_DTFLGS_RFC822 or ASN1_DTFLGS_ISO8601.

ASN1_TIME_to_tm() converts the time s to the standard tm structure. If s is NULL, then the current time is converted. The output time is GMT. The tm_sec, tm_min, tm_hour, tm_mday, tm_wday, tm_yday, tm_mon and tm_year fields of tm structure are set to proper values, whereas all other fields are set to 0. If tm is NULL this function performs a format check on s only. If s is in Generalized format with fractional seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while converting s to tm structure.

ASN1_TIME_diff() sets *pday and *psec to the time difference between from and to. If to represents a time later than from then one or both (depending on the time difference) of *pday and *psec will be positive. If to represents a time earlier than from then one or both of *pday and *psec will be negative. If to and from represent the same time then *pday and *psec will both be zero. If both *pday and *psec are nonzero they will always have the same sign. The value of *psec will always be less than the number of seconds in a day. If from or to is NULL the current time is used.

The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare the two times represented by the time structure s and the time_t t.

The ASN1_TIME_compare() function compares the two times represented by the time structures a and b.

The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an ASN1_GENERALIZEDTIME, regardless of year. If either out or *out are NULL, then a new object is allocated and must be freed after use.

The ASN1_TIME_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() functions duplicate the time structure t and return the duplicated result correspondingly.

"},{"location":"man3/ASN1_TIME_set/#notes","title":"NOTES","text":"

The ASN1_TIME structure corresponds to the ASN.1 structure Time defined in RFC5280 et al. The time setting functions obey the rules outlined in RFC5280: if the date can be represented by UTCTime it is used, else GeneralizedTime is used.

The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().

The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt is made to correct ancient calendar changes (for example from Julian to Gregorian calendars).

ASN1_UTCTIME is limited to a year range of 1950 through 2049.

Some applications add offset times directly to a time_t value and pass the results to ASN1_TIME_set() (or equivalent). This can cause problems as the time_t value can overflow on some systems resulting in unexpected results. New applications should use ASN1_TIME_adj() instead and pass the offset value in the offset_sec and offset_day parameters instead of directly manipulating a time_t value.

ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME, or vice versa, based on the resulting year. ASN1_GENERALIZEDTIME_adj() and ASN1_UTCTIME_adj() will not modify the type of the return structure.

It is recommended that functions starting with ASN1_TIME be used instead of those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific time format. The functions starting with ASN1_TIME will operate on either format.

"},{"location":"man3/ASN1_TIME_set/#bugs","title":"BUGS","text":"

ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() do not print out the timezone: it either prints out \"GMT\" or nothing. But all certificates complying with RFC5280 et al use GMT anyway.

ASN1_TIME_print(), ASN1_TIME_print_ex(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() do not distinguish if they fail because of an I/O error or invalid time format.

Use the ASN1_TIME_normalize() function to normalize the time value before printing to get GMT results.

"},{"location":"man3/ASN1_TIME_set/#return-values","title":"RETURN VALUES","text":"

ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_set() return a pointer to a time structure or NULL if an error occurred.

ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string() and ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise.

ASN1_TIME_normalize() returns 1 on success, and 0 on error.

ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1 if the structure is syntactically correct and 0 otherwise.

ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1 if the time is successfully printed out and 0 if an I/O error occurred an error occurred (I/O error or invalid time format).

ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an error occurred (invalid time format).

ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the passed-in time structure has invalid syntax, for example.

ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if s is before t, 0 if s equals t, or 1 if s is after t. -2 is returned on error.

ASN1_TIME_compare() returns -1 if a is before b, 0 if a equals b, or 1 if a is after b. -2 is returned on error.

ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time structure on success or NULL if an error occurred.

ASN1_TIME_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() return a pointer to a time structure or NULL if an error occurred.

"},{"location":"man3/ASN1_TIME_set/#examples","title":"EXAMPLES","text":"

Set a time structure to one hour after the current time and print it out:

#include <time.h>\n#include <openssl/asn1.h>\n\nASN1_TIME *tm;\ntime_t t;\nBIO *b;\n\nt = time(NULL);\ntm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);\nb = BIO_new_fp(stdout, BIO_NOCLOSE);\nASN1_TIME_print(b, tm);\nASN1_STRING_free(tm);\nBIO_free(b);\n

Determine if one time is later or sooner than the current time:

int day, sec;\n\nif (!ASN1_TIME_diff(&day, &sec, NULL, to))\n    /* Invalid time format */\n\nif (day > 0 || sec > 0)\n    printf(\"Later\\n\");\nelse if (day < 0 || sec < 0)\n    printf(\"Sooner\\n\");\nelse\n    printf(\"Same\\n\");\n
"},{"location":"man3/ASN1_TIME_set/#history","title":"HISTORY","text":"

The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1. The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1. The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1. The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1. The ASN1_TIME_compare() function was added in OpenSSL 1.1.1.

"},{"location":"man3/ASN1_TIME_set/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 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.

"},{"location":"man3/ASN1_TYPE_get/","title":"ASN1_TYPE_get","text":""},{"location":"man3/ASN1_TYPE_get/#name","title":"NAME","text":"

ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility functions

"},{"location":"man3/ASN1_TYPE_get/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_TYPE_get(const ASN1_TYPE *a);\nvoid ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);\nint ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);\nint ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);\n\nvoid *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);\nASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,\n                                   ASN1_TYPE **t);\n
"},{"location":"man3/ASN1_TYPE_get/#description","title":"DESCRIPTION","text":"

These functions allow an ASN1_TYPE structure to be manipulated. The ASN1_TYPE structure can contain any ASN.1 type or constructed type such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.

ASN1_TYPE_get() returns the type of a or 0 if it fails.

ASN1_TYPE_set() sets the value of a to type and value. This function uses the pointer value internally so it must not be freed up after the call.

ASN1_TYPE_set1() sets the value of a to type a copy of value.

ASN1_TYPE_cmp() compares ASN.1 types a and b and returns 0 if they are identical and nonzero otherwise.

ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in t using the ASN.1 structure it. If successful it returns a pointer to the ASN.1 structure corresponding to it which must be freed by the caller. If it fails it return NULL.

ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure s corresponding to it into an ASN1_TYPE. If successful the encoded ASN1_TYPE is returned. If t and *t are not NULL the encoded type is written to t overwriting any existing data. If t is not NULL but *t is NULL the returned ASN1_TYPE is written to *t.

"},{"location":"man3/ASN1_TYPE_get/#notes","title":"NOTES","text":"

The type and meaning of the value parameter for ASN1_TYPE_set() and ASN1_TYPE_set1() is determined by the type parameter. If type is V_ASN1_NULL value is ignored. If type is V_ASN1_BOOLEAN then the boolean is set to TRUE if value is not NULL. If type is V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise type is and ASN1_STRING structure. If type corresponds to a primitive type (or a string type) then the contents of the ASN1_STRING contain the content octets of the type. If type corresponds to a constructed type or a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and length octets).

ASN1_TYPE_cmp() may not return zero if two types are equivalent but have different encodings. For example the single content octet of the boolean TRUE value under BER can have any nonzero encoding but ASN1_TYPE_cmp() will only return zero if the values are the same.

If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the return value is nonzero. Technically if both parameters are NULL the two types could be absent OPTIONAL fields and so should match, however, passing NULL values could also indicate a programming error (for example an unparsable type which returns NULL) for types which do not match. So applications should handle the case of two absent values separately.

"},{"location":"man3/ASN1_TYPE_get/#return-values","title":"RETURN VALUES","text":"

ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.

ASN1_TYPE_set() does not return a value.

ASN1_TYPE_set1() returns 1 for success and 0 for failure.

ASN1_TYPE_cmp() returns 0 if the types are identical and nonzero otherwise.

ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or NULL on failure.

ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or NULL on failure.

"},{"location":"man3/ASN1_TYPE_get/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ASN1_aux_cb/","title":"ASN1_aux_cb","text":""},{"location":"man3/ASN1_aux_cb/#name","title":"NAME","text":"

ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb - ASN.1 auxiliary data

"},{"location":"man3/ASN1_aux_cb/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1t.h>\n\nstruct ASN1_AUX_st {\n    void *app_data;\n    int flags;\n    int ref_offset;             /* Offset of reference value */\n    int ref_lock;               /* Offset to an CRYPTO_RWLOCK */\n    ASN1_aux_cb *asn1_cb;\n    int enc_offset;             /* Offset of ASN1_ENCODING structure */\n    ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */\n};\ntypedef struct ASN1_AUX_st ASN1_AUX;\n\nstruct ASN1_PRINT_ARG_st {\n    BIO *out;\n    int indent;\n    const ASN1_PCTX *pctx;\n};\ntypedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;\n\nstruct ASN1_STREAM_ARG_st {\n    BIO *out;\n    BIO *ndef_bio;\n    unsigned char **boundary;\n};\ntypedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;\n\ntypedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,\n                        void *exarg);\ntypedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,\n                              const ASN1_ITEM *it, void *exarg);\n
"},{"location":"man3/ASN1_aux_cb/#description","title":"DESCRIPTION","text":"

ASN.1 data structures can be associated with an ASN1_AUX object to supply additional information about the ASN.1 structure. An ASN1_AUX structure is associated with the structure during the definition of the ASN.1 template. For example an ASN1_AUX structure will be associated by using one of the various ASN.1 template definition macros that supply auxiliary information such as ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(), ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().

An ASN1_AUX structure contains the following information.

During the processing of an ASN1_VALUE object the callbacks set via asn1_cb or asn1_const_cb will be invoked as a result of various events indicated via the operation parameter. The value of *in will be the ASN1_VALUE object being processed based on the template in it. An additional operation specific parameter may be passed in exarg. The currently supported operations are as follows. The callbacks should return a positive value on success or zero on error, unless otherwise noted below.

An ASN1_PRINT_ARG object is used during processing of ASN1_OP_PRINT_PRE and ASN1_OP_PRINT_POST callback operations. It contains the following information.

An ASN1_STREAM_ARG object is used during processing of ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and ASN1_OP_DETACHED_POST callback operations. It contains the following information.

"},{"location":"man3/ASN1_aux_cb/#return-values","title":"RETURN VALUES","text":"

The callbacks return 0 on error and a positive value on success. Some operations require specific positive success values as noted above.

"},{"location":"man3/ASN1_aux_cb/#see-also","title":"SEE ALSO","text":"

ASN1_item_new_ex(3)

"},{"location":"man3/ASN1_aux_cb/#history","title":"HISTORY","text":"

The ASN1_aux_const_cb() callback and the ASN1_OP_GET0_LIBCTX and ASN1_OP_GET0_PROPQ operation types were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_aux_cb/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2022 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.

"},{"location":"man3/ASN1_generate_nconf/","title":"ASN1_generate_nconf","text":""},{"location":"man3/ASN1_generate_nconf/#name","title":"NAME","text":"

ASN1_generate_nconf, ASN1_generate_v3 - ASN1 string generation functions

"},{"location":"man3/ASN1_generate_nconf/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);\nASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);\n
"},{"location":"man3/ASN1_generate_nconf/#description","title":"DESCRIPTION","text":"

These functions generate the ASN1 encoding of a string in an ASN1_TYPE structure.

str contains the string to encode. nconf or cnf contains the optional configuration information where additional strings will be read from. nconf will typically come from a config file whereas cnf is obtained from an X509V3_CTX structure, which will typically be used by X509 v3 certificate extension functions. cnf or nconf can be set to NULL if no additional configuration will be used.

"},{"location":"man3/ASN1_generate_nconf/#generation-string-format","title":"GENERATION STRING FORMAT","text":"

The actual data encoded is determined by the string str and the configuration information. The general format of the string is:

That is zero or more comma separated modifiers followed by a type followed by an optional colon and a value. The formats of type, value and modifier are explained below.

"},{"location":"man3/ASN1_generate_nconf/#supported-types","title":"Supported Types","text":"

The supported types are listed below. Case is not significant in the type names. Unless otherwise specified only the ASCII format is permissible.

"},{"location":"man3/ASN1_generate_nconf/#modifiers","title":"Modifiers","text":"

Modifiers affect the following structure, they can be used to add EXPLICIT or IMPLICIT tagging, add wrappers or to change the string format of the final type and value. The supported formats are documented below.

"},{"location":"man3/ASN1_generate_nconf/#return-values","title":"RETURN VALUES","text":"

ASN1_generate_nconf() and ASN1_generate_v3() return the encoded data as an ASN1_TYPE structure or NULL if an error occurred.

The error codes that can be obtained by ERR_get_error(3).

"},{"location":"man3/ASN1_generate_nconf/#examples","title":"EXAMPLES","text":"

A simple IA5String:

IA5STRING:Hello World\n

An IA5String explicitly tagged:

EXPLICIT:0,IA5STRING:Hello World\n

An IA5String explicitly tagged using APPLICATION tagging:

EXPLICIT:0A,IA5STRING:Hello World\n

A BITSTRING with bits 1 and 5 set and all others zero:

FORMAT:BITLIST,BITSTRING:1,5\n

A more complex example using a config file to produce a SEQUENCE consisting of a BOOL an OID and a UTF8String:

asn1 = SEQUENCE:seq_section\n\n[seq_section]\n\nfield1 = BOOLEAN:TRUE\nfield2 = OID:commonName\nfield3 = UTF8:Third field\n

This example produces an RSAPrivateKey structure, this is the key contained in the file client.pem in all OpenSSL distributions (note: the field names such as 'coeff' are ignored and are present just for clarity):

asn1=SEQUENCE:private_key\n[private_key]\nversion=INTEGER:0\n\nn=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\\\nD4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9\n\ne=INTEGER:0x010001\n\nd=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\\\nF810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D\n\np=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\\\nD4BD57\n\nq=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\\\n46EC4F\n\nexp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\\\n9C0A39B9\n\nexp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\\\nE7B2458F\n\ncoeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\\\n628657053A\n

This example is the corresponding public key in a SubjectPublicKeyInfo structure:

# # Start with a SEQUENCE asn1=SEQUENCE:pubkeyinfo

# # pubkeyinfo contains an algorithm identifier and the public key wrapped # # in a BIT STRING [pubkeyinfo] algorithm=SEQUENCE:rsa_alg pubkey=BITWRAP,SEQUENCE:rsapubkey

# # algorithm ID for RSA is just an OID and a NULL [rsa_alg] algorithm=OID:rsaEncryption parameter=NULL

# # Actual public key: modulus and exponent [rsapubkey] n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\\ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9

e=INTEGER:0x010001\n
"},{"location":"man3/ASN1_generate_nconf/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_generate_nconf/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2021 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.

"},{"location":"man3/ASN1_item_d2i_bio/","title":"ASN1_item_d2i_bio","text":""},{"location":"man3/ASN1_item_d2i_bio/#name","title":"NAME","text":"

ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio, ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack - decode and encode DER-encoded ASN.1 structures

"},{"location":"man3/ASN1_item_d2i_bio/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,\n                             long len, const ASN1_ITEM *it,\n                             OSSL_LIB_CTX *libctx, const char *propq);\nASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,\n                          long len, const ASN1_ITEM *it);\n\nvoid *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,\n                           OSSL_LIB_CTX *libctx, const char *propq);\nvoid *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);\n\nvoid *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,\n                          OSSL_LIB_CTX *libctx, const char *propq);\nvoid *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);\n\nBIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);\n\nASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct);\n\nvoid *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);\n\nvoid *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it,\n                         OSSL_LIB_CTX *libctx, const char *propq);\n
"},{"location":"man3/ASN1_item_d2i_bio/#description","title":"DESCRIPTION","text":"

ASN1_item_d2i_ex() decodes the contents of the data stored in *in of length len which must be a DER-encoded ASN.1 structure, using the ASN.1 template it. It places the result in *pval unless pval is NULL. If *pval is non-NULL on entry then the ASN1_VALUE present there will be reused. Otherwise a new ASN1_VALUE will be allocated. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTXprovided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching. On exit *in will be updated to point to the next byte in the buffer after the decoded structure.

ASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_d2i_bio_ex() decodes the contents of its input BIO in, which must be a DER-encoded ASN.1 structure, using the ASN.1 template it and places the result in *pval unless pval is NULL. If in is NULL it returns NULL, else a pointer to the parsed structure. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching.

ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE pointer is provided instead of a BIO.

ASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_i2d_mem_bio() encodes the given ASN.1 value val using the ASN.1 template it and returns the result in a memory BIO.

ASN1_item_pack() encodes the given ASN.1 value in obj using the ASN.1 template it and returns an ASN1_STRING object. If the passed in *oct is not NULL then this is used to store the returned result, otherwise a new ASN1_STRING object is created. If oct is not NULL and *oct is NULL then the returned return is also set into *oct. If there is an error the optional passed in ASN1_STRING will not be freed, but the previous value may be cleared when ASN1_STRING_set0(*oct, NULL, 0) is called internally.

ASN1_item_unpack() uses ASN1_item_d2i() to decode the DER-encoded ASN1_STRING oct using the ASN.1 template it.

ASN1_item_unpack_ex() is similar to ASN1_item_unpack(), but uses ASN1_item_d2i_ex() so that the libctx and propq can be used when doing algorithm fetching.

"},{"location":"man3/ASN1_item_d2i_bio/#return-values","title":"RETURN VALUES","text":"

ASN1_item_d2i_bio(), ASN1_item_unpack_ex() and ASN1_item_unpack() return a pointer to an ASN1_VALUE or NULL on error.

ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error.

ASN1_item_pack() returns a pointer to an ASN1_STRING or NULL on error.

"},{"location":"man3/ASN1_item_d2i_bio/#history","title":"HISTORY","text":"

The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex() and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0.

The function ASN1_item_unpack_ex() was added in OpenSSL 3.2.

"},{"location":"man3/ASN1_item_d2i_bio/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2023 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.

"},{"location":"man3/ASN1_item_new/","title":"ASN1_item_new","text":""},{"location":"man3/ASN1_item_new/#name","title":"NAME","text":"

ASN1_item_new_ex, ASN1_item_new - create new ASN.1 values

"},{"location":"man3/ASN1_item_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx,\n                             const char *propq);\nASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);\n
"},{"location":"man3/ASN1_item_new/#description","title":"DESCRIPTION","text":"

ASN1_item_new_ex() creates a new ASN1_VALUE structure based on the ASN1_ITEM template given in the it parameter. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching.

ASN1_item_new() is the same as ASN1_item_new_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

"},{"location":"man3/ASN1_item_new/#return-values","title":"RETURN VALUES","text":"

ASN1_item_new_ex() and ASN1_item_new() return a pointer to the newly created ASN1_VALUE or NULL on error.

"},{"location":"man3/ASN1_item_new/#history","title":"HISTORY","text":"

The function ASN1_item_new_ex() was added in OpenSSL 3.0.

"},{"location":"man3/ASN1_item_new/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/ASN1_item_sign/","title":"ASN1_item_sign","text":""},{"location":"man3/ASN1_item_sign/#name","title":"NAME","text":"

ASN1_item_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx, ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx - ASN1 sign and verify

"},{"location":"man3/ASN1_item_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nint ASN1_item_sign_ex(const ASN1_ITEM *it, X509_ALGOR *algor1,\n                      X509_ALGOR *algor2, ASN1_BIT_STRING *signature,\n                      const void *data, const ASN1_OCTET_STRING *id,\n                      EVP_PKEY *pkey, const EVP_MD *md, OSSL_LIB_CTX *libctx,\n                      const char *propq);\n\nint ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2,\n                   ASN1_BIT_STRING *signature, const void *data,\n                   EVP_PKEY *pkey, const EVP_MD *md);\n\nint ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1,\n                       X509_ALGOR *algor2, ASN1_BIT_STRING *signature,\n                       const void *data, EVP_MD_CTX *ctx);\n\nint ASN1_item_verify_ex(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                        const ASN1_BIT_STRING *signature, const void *data,\n                        const ASN1_OCTET_STRING *id, EVP_PKEY *pkey,\n                        OSSL_LIB_CTX *libctx, const char *propq);\n\nint ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                     const ASN1_BIT_STRING *signature, const void *data,\n                     EVP_PKEY *pkey);\n\nint ASN1_item_verify_ctx(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                         const ASN1_BIT_STRING *signature, const void *data,\n                         EVP_MD_CTX *ctx);\n
"},{"location":"man3/ASN1_item_sign/#description","title":"DESCRIPTION","text":"

ASN1_item_sign_ex() is used to sign arbitrary ASN1 data using a data object data, the ASN.1 structure it, private key pkey and message digest md. The data that is signed is formed by taking the data object in data and converting it to der format using the ASN.1 structure it. The data that will be signed, and a structure containing the signature may both have a copy of the X509_ALGOR. The ASN1_item_sign_ex() function will write the correct X509_ALGOR to the structs based on the algorithms and parameters that have been set up. If one of algor1 or algor2 points to the X509_ALGOR of the data to be signed, then that X509_ALGOR will first be written before the signature is generated. Examples of valid values that can be used by the ASN.1 structure it are ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and ASN1_ITEM_rptr(X509_CRL_INFO). The OSSL_LIB_CTX specified in libctx and the property query string specified in props are used when searching for algorithms in providers. The generated signature is set into signature. The optional parameter id can be NULL, but can be set for special key types. See EVP_PKEY_CTX_set1_id() for further info. The output parameters <algor1> and algor2 are ignored if they are NULL.

ASN1_item_sign() is similar to ASN1_item_sign_ex() but uses default values of NULL for the id, libctx and propq.

ASN1_item_sign_ctx() is similar to ASN1_item_sign() but uses the parameters contained in digest context ctx.

ASN1_item_verify_ex() is used to verify the signature signature of internal data data using the public key pkey and algorithm identifier alg. The data that is verified is formed by taking the data object in data and converting it to der format using the ASN.1 structure it. The OSSL_LIB_CTX specified in libctx and the property query string specified in props are used when searching for algorithms in providers. The optional parameter id can be NULL, but can be set for special key types. See EVP_PKEY_CTX_set1_id() for further info.

ASN1_item_verify() is similar to ASN1_item_verify_ex() but uses default values of NULL for the id, libctx and propq.

ASN1_item_verify_ctx() is similar to ASN1_item_verify() but uses the parameters contained in digest context ctx.

"},{"location":"man3/ASN1_item_sign/#return-values","title":"RETURN VALUES","text":"

All sign functions return the size of the signature in bytes for success and zero for failure.

All verify functions return 1 if the signature is valid and 0 if the signature check fails. If the signature could not be checked at all because it was ill-formed or some other error occurred then -1 is returned.

"},{"location":"man3/ASN1_item_sign/#examples","title":"EXAMPLES","text":"

In the following example a 'MyObject' object is signed using the key contained in an EVP_MD_CTX. The signature is written to MyObject.signature. The object is then output in DER format and then loaded back in and verified.

#include <openssl/x509.h>\n#include <openssl/asn1t.h>\n\n/* An object used to store the ASN1 data fields that will be signed */\ntypedef struct MySignInfoObject_st\n{\n    ASN1_INTEGER *version;\n    X509_ALGOR sig_alg;\n} MySignInfoObject;\n\nDECLARE_ASN1_FUNCTIONS(MySignInfoObject)\n/*\n * A higher level object containing the ASN1 fields, signature alg and\n * output signature.\n */\ntypedef struct MyObject_st\n{\n    MySignInfoObject info;\n    X509_ALGOR sig_alg;\n    ASN1_BIT_STRING *signature;\n} MyObject;\n\nDECLARE_ASN1_FUNCTIONS(MyObject)\n\n/* The ASN1 definition of MySignInfoObject */\nASN1_SEQUENCE_cb(MySignInfoObject, NULL) = {\n    ASN1_SIMPLE(MySignInfoObject, version, ASN1_INTEGER)\n    ASN1_EMBED(MySignInfoObject, sig_alg, X509_ALGOR),\n} ASN1_SEQUENCE_END_cb(MySignInfoObject, MySignInfoObject)\n\n/* new, free, d2i & i2d functions for MySignInfoObject */\nIMPLEMENT_ASN1_FUNCTIONS(MySignInfoObject)\n\n/* The ASN1 definition of MyObject */\nASN1_SEQUENCE_cb(MyObject, NULL) = {\n    ASN1_EMBED(MyObject, info, MySignInfoObject),\n    ASN1_EMBED(MyObject, sig_alg, X509_ALGOR),\n    ASN1_SIMPLE(MyObject, signature, ASN1_BIT_STRING)\n} ASN1_SEQUENCE_END_cb(MyObject, MyObject)\n\n/* new, free, d2i & i2d functions for MyObject */\nIMPLEMENT_ASN1_FUNCTIONS(MyObject)\n\nint test_asn1_item_sign_verify(const char *mdname, EVP_PKEY *pkey, long version)\n{\n   int ret = 0;\n   unsigned char *obj_der = NULL;\n   const unsigned char *p = NULL;\n   MyObject *obj = NULL, *loaded_obj = NULL;\n   const ASN1_ITEM *it = ASN1_ITEM_rptr(MySignInfoObject);\n   EVP_MD_CTX *sctx = NULL, *vctx = NULL;\n   int len;\n\n   /* Create MyObject and set its version */\n   obj = MyObject_new();\n   if (obj == NULL)\n       goto err;\n   if (!ASN1_INTEGER_set(obj->info.version, version))\n       goto err;\n\n   /* Set the key and digest used for signing */\n   sctx = EVP_MD_CTX_new();\n   if (sctx == NULL\n       || !EVP_DigestSignInit_ex(sctx, NULL, mdname, NULL, NULL, pkey))\n       goto err;\n\n   /*\n    * it contains the mapping between ASN.1 data and an object MySignInfoObject\n    * obj->info is the 'MySignInfoObject' object that will be\n    *   converted into DER data and then signed.\n    * obj->signature will contain the output signature.\n    * obj->sig_alg is filled with the private key's signing algorithm id.\n    * obj->info.sig_alg is another copy of the signing algorithm id that sits\n    * within MyObject.\n    */\n   len = ASN1_item_sign_ctx(it, &obj->sig_alg, &obj->info.sig_alg,\n                            obj->signature, &obj->info, sctx);\n   if (len <= 0\n       || X509_ALGOR_cmp(&obj->sig_alg, &obj->info.sig_alg) != 0)\n       goto err;\n\n   /* Output MyObject in der form */\n   len = i2d_MyObject(obj, &obj_der);\n   if (len <= 0)\n       goto err;\n\n   /* Set the key and digest used for verifying */\n   vctx = EVP_MD_CTX_new();\n   if (vctx == NULL\n       || !EVP_DigestVerifyInit_ex(vctx, NULL, mdname, NULL, NULL, pkey))\n       goto err;\n\n   /* Load the der data back into an object */\n   p = obj_der;\n   loaded_obj = d2i_MyObject(NULL, &p, len);\n   if (loaded_obj == NULL)\n       goto err;\n   /* Verify the loaded object */\n   ret = ASN1_item_verify_ctx(it, &loaded_obj->sig_alg, loaded_obj->signature,\n                              &loaded_obj->info, vctx);\n

err: OPENSSL_free(obj_der); MyObject_free(loaded_obj); MyObject_free(obj); EVP_MD_CTX_free(sctx); EVP_MD_CTX_free(vctx); return ret; }

"},{"location":"man3/ASN1_item_sign/#see-also","title":"SEE ALSO","text":"

X509_sign(3), X509_verify(3)

"},{"location":"man3/ASN1_item_sign/#history","title":"HISTORY","text":"

ASN1_item_sign_ex() and ASN1_item_verify_ex() were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_item_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2022 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.

"},{"location":"man3/ASYNC_WAIT_CTX_new/","title":"ASYNC_WAIT_CTX_new","text":""},{"location":"man3/ASYNC_WAIT_CTX_new/#name","title":"NAME","text":"

ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback, ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn, ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK, ASYNC_STATUS_EAGAIN - functions to manage waiting for asynchronous jobs to complete

"},{"location":"man3/ASYNC_WAIT_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/async.h>\n\n#define ASYNC_STATUS_UNSUPPORTED    0\n#define ASYNC_STATUS_ERR            1\n#define ASYNC_STATUS_OK             2\n#define ASYNC_STATUS_EAGAIN         3\ntypedef int (*ASYNC_callback_fn)(void *arg);\nASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);\nvoid ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);\nint ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,\n                               OSSL_ASYNC_FD fd,\n                               void *custom_data,\n                               void (*cleanup)(ASYNC_WAIT_CTX *, const void *,\n                                               OSSL_ASYNC_FD, void *));\nint ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,\n                          OSSL_ASYNC_FD *fd, void **custom_data);\nint ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,\n                               size_t *numfds);\nint ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,\n                                   size_t *numaddfds, OSSL_ASYNC_FD *delfd,\n                                   size_t *numdelfds);\nint ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);\nint ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,\n                                ASYNC_callback_fn callback,\n                                void *callback_arg);\nint ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,\n                                ASYNC_callback_fn *callback,\n                                void **callback_arg);\nint ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);\nint ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);\n
"},{"location":"man3/ASYNC_WAIT_CTX_new/#description","title":"DESCRIPTION","text":"

For an overview of how asynchronous operations are implemented in OpenSSL see ASYNC_start_job(3). An ASYNC_WAIT_CTX object represents an asynchronous \"session\", i.e. a related set of crypto operations. For example in SSL terms this would have a one-to-one correspondence with an SSL connection.

Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() function prior to calling ASYNC_start_job() (see ASYNC_start_job(3)). When the job is started it is associated with the ASYNC_WAIT_CTX for the duration of that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one time, but can be reused after an ASYNC_JOB has finished for a subsequent ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), application code cleans up with ASYNC_WAIT_CTX_free().

ASYNC_WAIT_CTXs can have \"wait\" file descriptors associated with them. Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in the ctx parameter will return the wait file descriptors associated with that job in *fd. The number of file descriptors returned will be stored in *numfds. It is the caller's responsibility to ensure that sufficient memory has been allocated in *fd to receive all the file descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL fd value will return no file descriptors but will still populate *numfds. Therefore, application code is typically expected to call this function twice: once to get the number of fds, and then again when sufficient memory has been allocated. If only one asynchronous engine is being used then normally this call will only ever return one fd. If multiple asynchronous engines are being used then more could be returned.

The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds have changed since the last call time ASYNC_start_job() returned ASYNC_PAUSE (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has been received). The numaddfds and numdelfds parameters will be populated with the number of fds added or deleted respectively. *addfd and *delfd will be populated with the list of added and deleted fds respectively. Similarly to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not NULL then the caller is responsible for ensuring sufficient memory is allocated.

Implementers of async aware code (e.g. engines) are encouraged to return a stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the \"churn\" of regularly changing fds - although no guarantees of this are provided to applications.

Applications can wait for the file descriptor to be ready for \"read\" using a system function call such as select or poll (being ready for \"read\" indicates that the job should be resumed). If no file descriptor is made available then an application will have to periodically \"poll\" the job by attempting to restart it to see if it is ready to continue.

Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job via ASYNC_get_wait_ctx(3) and provide a file descriptor to use for waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an engine immediately prior to calling ASYNC_pause_job() and not by end user code. An existing association with a file descriptor can be obtained using ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of these functions requires a key value which is unique to the async aware code. This could be any unique value but a good candidate might be the ENGINE * for the engine. The custom_data parameter can be any value, and will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a \"cleanup\" routine. This can be NULL but if provided will automatically get called when the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the fd or any other resources. Note: The \"cleanup\" routine does not get called if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().

An example of typical usage might be an async capable engine. User code would initiate cryptographic operations. The engine would initiate those operations asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by ASYNC_pause_job() to return control to the user code. The user code can then perform other tasks or wait for the job to be ready by calling \"select\" or other similar function on the wait file descriptor. The engine can signal to the user code that the job should be resumed by making the wait file descriptor \"readable\". Once resumed the engine should clear the wake signal on the wait file descriptor.

As well as a file descriptor, user code may also be notified via a callback. The callback and data pointers are stored within the ASYNC_WAIT_CTX along with an additional status field that can be used for the notification of retries from an engine. This additional method can be used when the user thinks that a file descriptor is too costly in terms of CPU cycles or in some context where a file descriptor is not appropriate.

ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The callback will be called to notify user code when an engine completes a cryptography operation. It is a requirement that the callback function is small and nonblocking as it will be run in the context of a polling mechanism or an interrupt.

ASYNC_WAIT_CTX_get_callback() returns the callback set in the ASYNC_WAIT_CTX structure.

ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status. The possible status values are the following:

ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value. If the status is any value other than ASYNC_STATUS_OK then the user code should not expect to receive a callback from the engine even if one has been set.

An example of the usage of the callback method might be the following. User code would initiate cryptographic operations, and the engine code would dispatch this operation to hardware, and if the dispatch is successful, then the engine code would call ASYNC_pause_job() to return control to the user code. After that, user code can perform other tasks. When the hardware completes the operation, normally it is detected by a polling function or an interrupt, as the user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously, then the registered callback will be called.

ASYNC_WAIT_CTX_free() frees up a single ASYNC_WAIT_CTX object. If the argument is NULL, nothing is done.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#return-values","title":"RETURN VALUES","text":"

ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or NULL on error.

ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. ASYNC_WAIT_CTX_get_status() returns the engine status.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#notes","title":"NOTES","text":"

On Windows platforms the <openssl/async.h> header is dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/async.h>.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#see-also","title":"SEE ALSO","text":"

crypto(7), ASYNC_start_job(3)

"},{"location":"man3/ASYNC_WAIT_CTX_new/#history","title":"HISTORY","text":"

ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(), ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(), ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd() were added in OpenSSL 1.1.0.

ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(), ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status() were added in OpenSSL 3.0.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/ASYNC_start_job/","title":"ASYNC_start_job","text":""},{"location":"man3/ASYNC_start_job/#name","title":"NAME","text":"

ASYNC_get_wait_ctx, ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable, ASYNC_stack_alloc_fn, ASYNC_stack_free_fn, ASYNC_set_mem_functions, ASYNC_get_mem_functions - asynchronous job management functions

"},{"location":"man3/ASYNC_start_job/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/async.h>\n\nint ASYNC_init_thread(size_t max_size, size_t init_size);\nvoid ASYNC_cleanup_thread(void);\n\nint ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,\n                    int (*func)(void *), void *args, size_t size);\nint ASYNC_pause_job(void);\n\nASYNC_JOB *ASYNC_get_current_job(void);\nASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);\nvoid ASYNC_block_pause(void);\nvoid ASYNC_unblock_pause(void);\n\nint ASYNC_is_capable(void);\n\ntypedef void *(*ASYNC_stack_alloc_fn)(size_t *num);\ntypedef void (*ASYNC_stack_free_fn)(void *addr);\nint ASYNC_set_mem_functions(ASYNC_stack_alloc_fn alloc_fn,\n                            ASYNC_stack_free_fn free_fn);\nvoid ASYNC_get_mem_functions(ASYNC_stack_alloc_fn *alloc_fn,\n                             ASYNC_stack_free_fn *free_fn);\n
"},{"location":"man3/ASYNC_start_job/#description","title":"DESCRIPTION","text":"

OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This represents code that can be started and executes until some event occurs. At that point the code can be paused and control returns to user code until some subsequent event indicates that the job can be resumed. It's OpenSSL specific implementation of cooperative multitasking.

The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for efficiency reasons, jobs can be created up front and reused many times. They are held in a pool until they are needed, at which point they are removed from the pool, used, and then returned to the pool when the job completes. If the user application is multi-threaded, then ASYNC_init_thread() may be called for each thread that will initiate asynchronous jobs. Before user code exits per-thread resources need to be cleaned up. This will normally occur automatically (see OPENSSL_init_crypto(3)) but may be explicitly initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to ensure this will result in memory leaks.

The max_size argument limits the number of ASYNC_JOBs that will be held in the pool. If max_size is set to 0 then no upper limit is set. When an ASYNC_JOB is needed but there are none available in the pool already then one will be automatically created, as long as the total of ASYNC_JOBs managed by the pool does not exceed max_size. When the pool is first initialised init_size ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is not called before the pool is first used then it will be called automatically with a max_size of 0 (no upper limit) and an init_size of 0 (no ASYNC_JOBs created up front).

An asynchronous job is started by calling the ASYNC_start_job() function. Initially *job should be NULL. ctx should point to an ASYNC_WAIT_CTX object created through the ASYNC_WAIT_CTX_new(3) function. ret should point to a location where the return value of the asynchronous function should be stored on completion of the job. func represents the function that should be started asynchronously. The data pointed to by args and of size size will be copied and then passed as an argument to func when the job starts. ASYNC_start_job will return one of the following values:

At any one time there can be a maximum of one job actively running per thread (you can have many that are paused). ASYNC_get_current_job() can be used to get a pointer to the currently executing ASYNC_JOB. If no job is currently executing then this will return NULL.

If executing within the context of a job (i.e. having been called directly or indirectly by the function \"func\" passed as an argument to ASYNC_start_job()) then ASYNC_pause_job() will immediately return control to the calling application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the *job parameter will resume execution from the ASYNC_pause_job() call. If ASYNC_pause_job() is called whilst not within the context of a job then no action is taken and ASYNC_pause_job() returns immediately.

ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX for the job (see ASYNC_WAIT_CTX_new(3)). ASYNC_WAIT_CTXs contain two different ways to notify applications that a job is ready to be resumed. One is a \"wait\" file descriptor, and the other is a \"callback\" mechanism.

The \"wait\" file descriptor associated with ASYNC_WAIT_CTX is used for applications to wait for the file descriptor to be ready for \"read\" using a system function call such as select(2) or poll(2) (being ready for \"read\" indicates that the job should be resumed). If no file descriptor is made available then an application will have to periodically \"poll\" the job by attempting to restart it to see if it is ready to continue.

ASYNC_WAIT_CTXs also have a \"callback\" mechanism to notify applications. The callback is set by an application, and it will be automatically called when an engine completes a cryptography operation, so that the application can resume the paused work flow without polling. An engine could be written to look whether the callback has been set. If it has then it would use the callback mechanism in preference to the file descriptor notifications. If a callback is not set then the engine may use file descriptor based notifications. Please note that not all engines may support the callback mechanism, so the callback may not be used even if it has been set. See ASYNC_WAIT_CTX_new() for more details.

The ASYNC_block_pause() function will prevent the currently active job from pausing. The block will remain in place until a subsequent call to ASYNC_unblock_pause(). These functions can be nested, e.g. if you call ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in order to re-enable pausing. If these functions are called while there is no currently active job then they have no effect. This functionality can be useful to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an application acquires a lock. It then calls some cryptographic function which invokes ASYNC_pause_job(). This returns control back to the code that created the ASYNC_JOB. If that code then attempts to acquire the same lock before resuming the original job then a deadlock can occur. By calling ASYNC_block_pause() immediately after acquiring the lock and ASYNC_unblock_pause() immediately before releasing it then this situation cannot occur.

Some platforms cannot support async operations. The ASYNC_is_capable() function can be used to detect whether the current platform is async capable or not.

Custom memory allocation functions are supported for the POSIX platform. Custom memory allocation functions allow alternative methods of allocating stack memory such as mmap, or using stack memory from the current thread. Using an ASYNC_stack_alloc_fn callback also allows manipulation of the stack size, which defaults to 32k. The stack size can be altered by allocating a stack of a size different to the requested size, and passing back the new stack size in the callback's *num parameter.

"},{"location":"man3/ASYNC_start_job/#return-values","title":"RETURN VALUES","text":"

ASYNC_init_thread returns 1 on success or 0 otherwise.

ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or ASYNC_FINISH as described above.

ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when not within the context of an ASYNC_JOB then this is counted as success so 1 is returned.

ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or NULL if not within the context of a job.

ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.

ASYNC_is_capable() returns 1 if the current platform is async capable or 0 otherwise.

ASYNC_set_mem_functions returns 1 if custom stack allocators are supported by the current platform and no allocations have already occurred or 0 otherwise.

"},{"location":"man3/ASYNC_start_job/#notes","title":"NOTES","text":"

On Windows platforms the <openssl/async.h> header is dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/async.h>.

"},{"location":"man3/ASYNC_start_job/#examples","title":"EXAMPLES","text":"

The following example demonstrates how to use most of the core async APIs:

#ifdef _WIN32\n

# # include #endif #include #include #include #include 

int unique = 0;\n\nvoid cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)\n{\n    OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;\n\n    close(r);\n    close(*w);\n    OPENSSL_free(w);\n}\n\nint jobfunc(void *arg)\n{\n    ASYNC_JOB *currjob;\n    unsigned char *msg;\n    int pipefds[2] = {0, 0};\n    OSSL_ASYNC_FD *wptr;\n    char buf = 'X';\n\n    currjob = ASYNC_get_current_job();\n    if (currjob != NULL) {\n        printf(\"Executing within a job\\n\");\n    } else {\n        printf(\"Not executing within a job - should not happen\\n\");\n        return 0;\n    }\n\n    msg = (unsigned char *)arg;\n    printf(\"Passed in message is: %s\\n\", msg);\n\n    /*\n     * Create a way to inform the calling thread when this job is ready\n     * to resume, in this example we're using file descriptors.\n     * For offloading the task to an asynchronous ENGINE it's not necessary,\n     * the ENGINE should handle that internally.\n     */\n\n    if (pipe(pipefds) != 0) {\n        printf(\"Failed to create pipe\\n\");\n        return 0;\n    }\n    wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));\n    if (wptr == NULL) {\n        printf(\"Failed to malloc\\n\");\n        return 0;\n    }\n    *wptr = pipefds[1];\n    ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,\n                               pipefds[0], wptr, cleanup);\n\n    /*\n     * Normally some external event (like a network read being ready,\n     * disk access being finished, or some hardware offload operation\n     * completing) would cause this to happen at some\n     * later point - but we do it here for demo purposes, i.e.\n     * immediately signalling that the job is ready to be woken up after\n     * we return to main via ASYNC_pause_job().\n     */\n    write(pipefds[1], &buf, 1);\n\n    /*\n     * Return control back to main just before calling a blocking\n     * method. The main thread will wait until pipefds[0] is ready\n     * for reading before returning control to this thread.\n     */\n    ASYNC_pause_job();\n\n    /* Perform the blocking call (it won't block with this example code) */\n    read(pipefds[0], &buf, 1);\n\n    printf (\"Resumed the job after a pause\\n\");\n\n    return 1;\n}\n\nint main(void)\n{\n    ASYNC_JOB *job = NULL;\n    ASYNC_WAIT_CTX *ctx = NULL;\n    int ret;\n    OSSL_ASYNC_FD waitfd;\n    fd_set waitfdset;\n    size_t numfds;\n    unsigned char msg[13] = \"Hello world!\";\n\n    printf(\"Starting...\\n\");\n\n    ctx = ASYNC_WAIT_CTX_new();\n    if (ctx == NULL) {\n        printf(\"Failed to create ASYNC_WAIT_CTX\\n\");\n        abort();\n    }\n\n    for (;;) {\n        switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {\n        case ASYNC_ERR:\n        case ASYNC_NO_JOBS:\n            printf(\"An error occurred\\n\");\n            goto end;\n        case ASYNC_PAUSE:\n            printf(\"Job was paused\\n\");\n            break;\n        case ASYNC_FINISH:\n            printf(\"Job finished with return value %d\\n\", ret);\n            goto end;\n        }\n\n        /* Get the file descriptor we can use to wait for the job\n         * to be ready to be woken up\n         */\n        printf(\"Waiting for the job to be woken up\\n\");\n\n        if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)\n                || numfds > 1) {\n            printf(\"Unexpected number of fds\\n\");\n            abort();\n        }\n        ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);\n        FD_ZERO(&waitfdset);\n        FD_SET(waitfd, &waitfdset);\n\n        /* Wait for the job to be ready for wakeup */\n        select(waitfd + 1, &waitfdset, NULL, NULL, NULL);\n    }\n\nend:\n    ASYNC_WAIT_CTX_free(ctx);\n    printf(\"Finishing\\n\");\n\n    return 0;\n}\n

The expected output from executing the above example program is:

Starting...\nExecuting within a job\nPassed in message is: Hello world!\nJob was paused\nWaiting for the job to be woken up\nResumed the job after a pause\nJob finished with return value 1\nFinishing\n
"},{"location":"man3/ASYNC_start_job/#see-also","title":"SEE ALSO","text":"

crypto(7), ERR_print_errors(3)

"},{"location":"man3/ASYNC_start_job/#history","title":"HISTORY","text":"

ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first added in OpenSSL 1.1.0.

"},{"location":"man3/ASYNC_start_job/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/BF_encrypt/","title":"BF_encrypt","text":""},{"location":"man3/BF_encrypt/#name","title":"NAME","text":"

BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption

"},{"location":"man3/BF_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/blowfish.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void BF_set_key(BF_KEY *key, int len, const unsigned char *data);\n\nvoid BF_ecb_encrypt(const unsigned char *in, unsigned char *out,\n                    BF_KEY *key, int enc);\nvoid BF_cbc_encrypt(const unsigned char *in, unsigned char *out,\n                    long length, BF_KEY *schedule,\n                    unsigned char *ivec, int enc);\nvoid BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                      long length, BF_KEY *schedule,\n                      unsigned char *ivec, int *num, int enc);\nvoid BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                      long length, BF_KEY *schedule,\n                      unsigned char *ivec, int *num);\nconst char *BF_options(void);\n\nvoid BF_encrypt(BF_LONG *data, const BF_KEY *key);\nvoid BF_decrypt(BF_LONG *data, const BF_KEY *key);\n
"},{"location":"man3/BF_encrypt/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3) and EVP_EncryptFinal_ex(3) or the equivalently named decrypt functions.

This library implements the Blowfish cipher, which was invented and described by Counterpane (see http://www.counterpane.com/blowfish.html ).

Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. It uses a variable size key, but typically, 128 bit (16 byte) keys are considered good for strong encryption. Blowfish can be used in the same modes as DES (see des_modes(7)). Blowfish is currently one of the faster block ciphers. It is quite a bit faster than DES, and much faster than IDEA or RC2.

Blowfish consists of a key setup phase and the actual encryption or decryption phase.

BF_set_key() sets up the BF_KEY key using the len bytes long key at data.

BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. It encrypts or decrypts the first 64 bits of in using the key key, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. The vector pointed at by in and out must be 64 bits in length, no less. If they are larger, everything after the first 64 bits is ignored.

The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() all operate on variable length data. They all take an initialization vector ivec which needs to be passed along into the next call of the same function for the same message. ivec may be initialized with anything, but the recipient needs to know what it was initialized with, or it won't be able to decrypt. Some programs and protocols simplify this, like SSH, where ivec is simply initialized to zero. BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt a variable number of bytes (the amount does not have to be an exact multiple of 8). The purpose of the latter two is to simulate stream ciphers, and therefore, they need the parameter num, which is a pointer to an integer where the current offset in ivec is stored between calls. This integer must be initialized to zero when ivec is initialized.

BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It encrypts or decrypts the 64 bits chunks of in using the key schedule, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long initialization vector.

BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. It encrypts or decrypts the bytes in in using the key schedule, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long initialization vector. num must point at an integer which must be initially zero.

BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. It uses the same parameters as BF_cfb64_encrypt(), which must be initialized the same way.

BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish encryption. They encrypt/decrypt the first 64 bits of the vector pointed by data, using the key key. These functions should not be used unless you implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). If you still want to use these functions, you should be aware that they take each 32-bit chunk in host-byte order, which is little-endian on little-endian platforms and big-endian on big-endian ones.

"},{"location":"man3/BF_encrypt/#return-values","title":"RETURN VALUES","text":"

None of the functions presented here return any value.

"},{"location":"man3/BF_encrypt/#note","title":"NOTE","text":"

Applications should use the higher level functions EVP_EncryptInit(3) etc. instead of calling these functions directly.

"},{"location":"man3/BF_encrypt/#see-also","title":"SEE ALSO","text":"

EVP_EncryptInit(3), des_modes(7)

"},{"location":"man3/BF_encrypt/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/BF_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BIO_ADDR/","title":"BIO_ADDR","text":""},{"location":"man3/BIO_ADDR/#name","title":"NAME","text":"

BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, BIO_ADDR_hostname_string, BIO_ADDR_service_string, BIO_ADDR_path_string - BIO_ADDR routines

"},{"location":"man3/BIO_ADDR/#synopsis","title":"SYNOPSIS","text":"
#include <sys/types.h>\n#include <openssl/bio.h>\n\ntypedef union bio_addr_st BIO_ADDR;\n\nBIO_ADDR *BIO_ADDR_new(void);\nint BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);\nBIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);\nvoid BIO_ADDR_free(BIO_ADDR *ap);\nvoid BIO_ADDR_clear(BIO_ADDR *ap);\nint BIO_ADDR_rawmake(BIO_ADDR *ap, int family,\n                     const void *where, size_t wherelen, unsigned short port);\nint BIO_ADDR_family(const BIO_ADDR *ap);\nint BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);\nunsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);\nchar *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);\nchar *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);\nchar *BIO_ADDR_path_string(const BIO_ADDR *ap);\n
"},{"location":"man3/BIO_ADDR/#description","title":"DESCRIPTION","text":"

The BIO_ADDR type is a wrapper around all types of socket addresses that OpenSSL deals with, currently transparently supporting AF_INET, AF_INET6 and AF_UNIX according to what's available on the platform at hand.

BIO_ADDR_new() creates a new unfilled BIO_ADDR, to be used with routines that will fill it with information, such as BIO_accept_ex().

BIO_ADDR_copy() copies the contents of src into dst. Neither src or dst can be NULL.

BIO_ADDR_dup() creates a new BIO_ADDR, with a copy of the address data in ap.

BIO_ADDR_free() frees a BIO_ADDR created with BIO_ADDR_new() or BIO_ADDR_dup(). If the argument is NULL, nothing is done.

BIO_ADDR_clear() clears any data held within the provided BIO_ADDR and sets it back to an uninitialised state.

BIO_ADDR_rawmake() takes a protocol family, a byte array of size wherelen with an address in network byte order pointed at by where and a port number in network byte order in port (except for the AF_UNIX protocol family, where port is meaningless and therefore ignored) and populates the given BIO_ADDR with them. In case this creates a AF_UNIX BIO_ADDR, wherelen is expected to be the length of the path string (not including the terminating NUL, such as the result of a call to strlen()). Read on about the addresses in \"RAW ADDRESSES\" below.

BIO_ADDR_family() returns the protocol family of the given BIO_ADDR. The possible non-error results are one of the constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the BIO_ADDR has not been initialised.

BIO_ADDR_rawaddress() will write the raw address of the given BIO_ADDR in the area pointed at by p if p is non-NULL, and will set *l to be the amount of bytes the raw address takes up if l is non-NULL. A technique to only find out the size of the address is a call with p set to NULL. The raw address will be in network byte order, most significant byte first. In case this is a AF_UNIX BIO_ADDR, l gets the length of the path string (not including the terminating NUL, such as the result of a call to strlen()). Read on about the addresses in \"RAW ADDRESSES\" below.

BIO_ADDR_rawport() returns the raw port of the given BIO_ADDR. The raw port will be in network byte order.

BIO_ADDR_hostname_string() returns a character string with the hostname of the given BIO_ADDR. If numeric is 1, the string will contain the numerical form of the address. This only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

BIO_ADDR_service_string() returns a character string with the service name of the port of the given BIO_ADDR. If numeric is 1, the string will contain the port number. This only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

BIO_ADDR_path_string() returns a character string with the path of the given BIO_ADDR. This only works for BIO_ADDR of the protocol family AF_UNIX. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

"},{"location":"man3/BIO_ADDR/#raw-addresses","title":"RAW ADDRESSES","text":"

Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a network byte order address of a specific site. Internally, those are treated as a pointer to struct in_addr (for AF_INET), struct in6_addr (for AF_INET6) or char * (for AF_UNIX), all depending on the protocol family the address is for.

"},{"location":"man3/BIO_ADDR/#return-values","title":"RETURN VALUES","text":"

The string producing functions BIO_ADDR_hostname_string(), BIO_ADDR_service_string() and BIO_ADDR_path_string() will return NULL on error and leave an error indication on the OpenSSL error stack.

BIO_ADDR_copy() returns 1 on success or 0 on error.

All other functions described here return 0 or NULL when the information they should return isn't available.

"},{"location":"man3/BIO_ADDR/#see-also","title":"SEE ALSO","text":"

BIO_connect(3), BIO_s_connect(3)

"},{"location":"man3/BIO_ADDR/#history","title":"HISTORY","text":"

BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2.

"},{"location":"man3/BIO_ADDR/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/BIO_ADDRINFO/","title":"BIO_ADDRINFO","text":""},{"location":"man3/BIO_ADDRINFO/#name","title":"NAME","text":"

BIO_lookup_type, BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, BIO_ADDRINFO_address, BIO_lookup_ex, BIO_lookup - BIO_ADDRINFO type and routines

"},{"location":"man3/BIO_ADDRINFO/#synopsis","title":"SYNOPSIS","text":"
#include <sys/types.h>\n#include <openssl/bio.h>\n\ntypedef union bio_addrinfo_st BIO_ADDRINFO;\n\nenum BIO_lookup_type {\n    BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER\n};\n\nint BIO_lookup_ex(const char *host, const char *service, int lookup_type,\n                  int family, int socktype, int protocol, BIO_ADDRINFO **res);\nint BIO_lookup(const char *host, const char *service,\n               enum BIO_lookup_type lookup_type,\n               int family, int socktype, BIO_ADDRINFO **res);\n\nconst BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);\nconst BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);\nvoid BIO_ADDRINFO_free(BIO_ADDRINFO *bai);\n
"},{"location":"man3/BIO_ADDRINFO/#description","title":"DESCRIPTION","text":"

The BIO_ADDRINFO type is a wrapper for address information types provided on your platform.

BIO_ADDRINFO normally forms a chain of several that can be picked at one by one.

BIO_lookup_ex() looks up a specified host and service, and uses lookup_type to determine what the default address should be if host is NULL. family, socktype and protocol are used to determine what protocol family, socket type and protocol should be used for the lookup. family can be any of AF_INET, AF_INET6, AF_UNIX and AF_UNSPEC. socktype can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0 indicates that any type can be used. protocol specifies a protocol such as IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be used. res points at a pointer to hold the start of a BIO_ADDRINFO chain.

For the family AF_UNIX, BIO_lookup_ex() will ignore the service parameter and expects the host parameter to hold the path to the socket file.

BIO_lookup() does the same as BIO_lookup_ex() but does not provide the ability to select based on the protocol (any protocol may be returned).

BIO_ADDRINFO_family() returns the family of the given BIO_ADDRINFO. The result will be one of the constants AF_INET, AF_INET6 and AF_UNIX.

BIO_ADDRINFO_socktype() returns the socket type of the given BIO_ADDRINFO. The result will be one of the constants SOCK_STREAM and SOCK_DGRAM.

BIO_ADDRINFO_protocol() returns the protocol id of the given BIO_ADDRINFO. The result will be one of the constants IPPROTO_TCP and IPPROTO_UDP.

BIO_ADDRINFO_address() returns the underlying BIO_ADDR of the given BIO_ADDRINFO.

BIO_ADDRINFO_next() returns the next BIO_ADDRINFO in the chain from the given one.

BIO_ADDRINFO_free() frees the chain of BIO_ADDRINFO starting with the given one. If the argument is NULL, nothing is done.

"},{"location":"man3/BIO_ADDRINFO/#return-values","title":"RETURN VALUES","text":"

BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error occurred, and will leave an error indication on the OpenSSL error stack in that case.

All other functions described here return 0 or NULL when the information they should return isn't available.

"},{"location":"man3/BIO_ADDRINFO/#notes","title":"NOTES","text":"

The BIO_lookup_ex() implementation uses the platform provided getaddrinfo() function. On Linux it is known that specifying 0 for the protocol will not return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP address is required then the protocol parameter to BIO_lookup_ex() should be explicitly set to IPPROTO_SCTP. The same may be true on other platforms.

"},{"location":"man3/BIO_ADDRINFO/#history","title":"HISTORY","text":"

The BIO_lookup_ex() function was added in OpenSSL 1.1.1.

"},{"location":"man3/BIO_ADDRINFO/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/BIO_connect/","title":"BIO_connect","text":""},{"location":"man3/BIO_connect/#name","title":"NAME","text":"

BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO socket communication setup routines

"},{"location":"man3/BIO_connect/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_socket(int domain, int socktype, int protocol, int options);\nint BIO_bind(int sock, const BIO_ADDR *addr, int options);\nint BIO_connect(int sock, const BIO_ADDR *addr, int options);\nint BIO_listen(int sock, const BIO_ADDR *addr, int options);\nint BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);\nint BIO_closesocket(int sock);\n
"},{"location":"man3/BIO_connect/#description","title":"DESCRIPTION","text":"

BIO_socket() creates a socket in the domain domain, of type socktype and protocol. Socket options are currently unused, but is present for future use.

BIO_bind() binds the source address and service to a socket and may be useful before calling BIO_connect(). The options may include BIO_SOCK_REUSEADDR, which is described in \"FLAGS\" below.

BIO_connect() connects sock to the address and service given by addr. Connection options may be zero or any combination of BIO_SOCK_KEEPALIVE, BIO_SOCK_NONBLOCK and BIO_SOCK_NODELAY. The flags are described in \"FLAGS\" below.

BIO_listen() has sock start listening on the address and service given by addr. Connection options may be zero or any combination of BIO_SOCK_KEEPALIVE, BIO_SOCK_NONBLOCK, BIO_SOCK_NODELAY, BIO_SOCK_REUSEADDR and BIO_SOCK_V6_ONLY. The flags are described in \"FLAGS\" below.

BIO_accept_ex() waits for an incoming connections on the given socket accept_sock. When it gets a connection, the address and port of the peer gets stored in peer if that one is non-NULL. Accept options may be zero or BIO_SOCK_NONBLOCK, and is applied on the accepted socket. The flags are described in \"FLAGS\" below.

BIO_closesocket() closes sock.

"},{"location":"man3/BIO_connect/#flags","title":"FLAGS","text":"

These flags are bit flags, so they are to be combined with the | operator, for example:

BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);\n
"},{"location":"man3/BIO_connect/#return-values","title":"RETURN VALUES","text":"

BIO_socket() returns the socket number on success or INVALID_SOCKET (-1) on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

BIO_accept_ex() returns the accepted socket on success or INVALID_SOCKET (-1) on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

"},{"location":"man3/BIO_connect/#see-also","title":"SEE ALSO","text":"

BIO_ADDR(3)

"},{"location":"man3/BIO_connect/#history","title":"HISTORY","text":"

BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0. Use the functions described above instead.

"},{"location":"man3/BIO_connect/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2022 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.

"},{"location":"man3/BIO_ctrl/","title":"BIO_ctrl","text":""},{"location":"man3/BIO_ctrl/#name","title":"NAME","text":"

BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo - BIO control operations

"},{"location":"man3/BIO_ctrl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef int BIO_info_cb(BIO *b, int state, int res);\n\nlong BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);\nlong BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);\nvoid *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);\nlong BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);\n\nint BIO_reset(BIO *b);\nint BIO_seek(BIO *b, int ofs);\nint BIO_tell(BIO *b);\nint BIO_flush(BIO *b);\nint BIO_eof(BIO *b);\nint BIO_set_close(BIO *b, long flag);\nint BIO_get_close(BIO *b);\nint BIO_pending(BIO *b);\nint BIO_wpending(BIO *b);\nsize_t BIO_ctrl_pending(BIO *b);\nsize_t BIO_ctrl_wpending(BIO *b);\n\nint BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);\nint BIO_set_info_callback(BIO *b, BIO_info_cb *cb);\n\nint BIO_get_ktls_send(BIO *b);\nint BIO_get_ktls_recv(BIO *b);\n\nint BIO_set_conn_mode(BIO *b, int mode);\nint BIO_get_conn_mode(BIO *b);\n\nint BIO_set_tfo(BIO *b, int onoff);\n
"},{"location":"man3/BIO_ctrl/#description","title":"DESCRIPTION","text":"

BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() are BIO \"control\" operations taking arguments of various types. These functions are not normally called directly, various macros are used instead. The standard macros are described below, macros specific to a particular type of BIO are described in the specific BIOs manual page as well as any special features of the standard calls.

BIO_reset() typically resets a BIO to some initial state, in the case of file related BIOs for example it rewinds the file pointer to the start of the file.

BIO_seek() resets a file related BIO's (that is file descriptor and FILE BIOs) file position pointer to ofs bytes from start of file.

BIO_tell() returns the current file position of a file related BIO.

BIO_flush() normally writes out any internally buffered data, in some cases it is used to signal EOF and that no more data will be written.

BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of \"EOF\" varies according to the BIO type.

BIO_set_close() sets the BIO b close flag to flag. flag can take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used in a source/sink BIO to indicate that the underlying I/O stream should be closed when the BIO is freed.

BIO_get_close() returns the BIOs close flag.

BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the number of pending characters in the BIOs read and write buffers. Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() return a size_t type and are functions, BIO_pending() and BIO_wpending() are macros which call BIO_ctrl().

BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for sending. Otherwise, it returns zero. BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for receiving. Otherwise, it returns zero.

BIO_get_conn_mode() returns the BIO connection mode. BIO_set_conn_mode() sets the BIO connection mode.

BIO_set_tfo() disables TCP Fast Open when onoff is 0, and enables TCP Fast Open when onoff is nonzero. Setting the value to 1 is equivalent to setting BIO_SOCK_TFO in BIO_set_conn_mode().

"},{"location":"man3/BIO_ctrl/#return-values","title":"RETURN VALUES","text":"

BIO_reset() normally returns 1 for success and <=0 for failure. File BIOs are an exception, they return 0 for success and -1 for failure.

BIO_seek() and BIO_tell() both return the current file position on success and -1 for failure, except file BIOs which for BIO_seek() always return 0 for success and -1 for failure.

BIO_flush() returns 1 for success and <=0 for failure.

BIO_eof() returns 1 if EOF has been reached, 0 if not, or negative values for failure.

BIO_set_close() returns 1 on success or <=0 for failure.

BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also returns other negative values if an error occurs.

BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the amount of pending data. BIO_pending() and BIO_wpending() return negative value or 0 on error. BIO_ctrl_pending() and BIO_ctrl_wpending() return 0 on error.

BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for sending. Otherwise, it returns zero. BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for receiving. Otherwise, it returns zero.

BIO_set_conn_mode() returns 1 for success and 0 for failure. BIO_get_conn_mode() returns the current connection mode. Which may contain the bitwise-or of the following flags:

BIO_SOCK_REUSEADDR\nBIO_SOCK_V6_ONLY\nBIO_SOCK_KEEPALIVE\nBIO_SOCK_NONBLOCK\nBIO_SOCK_NODELAY\nBIO_SOCK_TFO\n

BIO_set_tfo() returns 1 for success, and 0 for failure.

"},{"location":"man3/BIO_ctrl/#notes","title":"NOTES","text":"

BIO_flush(), because it can write data may return 0 or -1 indicating that the call should be retried later in a similar manner to BIO_write_ex(). The BIO_should_retry() call should be used and appropriate action taken is the call fails.

The return values of BIO_pending() and BIO_wpending() may not reliably determine the amount of pending data in all cases. For example in the case of a file BIO some data may be available in the FILE structures internal buffers but it is not possible to determine this in a portably way. For other types of BIO they may not be supported.

Filter BIOs if they do not internally handle a particular BIO_ctrl() operation usually pass the operation to the next BIO in the chain. This often means there is no need to locate the required BIO for a particular operation, it can be called on a chain and it will be automatically passed to the relevant BIO. However, this can cause unexpected results: for example no current filter BIOs implement BIO_seek(), but this may still succeed if the chain ends in a FILE or file descriptor BIO.

Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() operation.

"},{"location":"man3/BIO_ctrl/#bugs","title":"BUGS","text":"

Some of the return values are ambiguous and care should be taken. In particular a return value of 0 can be returned if an operation is not supported, if an error occurred, if EOF has not been reached and in the case of BIO_seek() on a file BIO for a successful operation.

In older versions of OpenSSL the BIO_ctrl_pending() and BIO_ctrl_wpending() could return values greater than INT_MAX on error.

"},{"location":"man3/BIO_ctrl/#history","title":"HISTORY","text":"

The BIO_get_ktls_send() and BIO_get_ktls_recv() macros were added in OpenSSL 3.0. They were modified to never return -1 in OpenSSL 3.0.4.

The BIO_get_conn_mode(), BIO_set_conn_mode() and BIO_set_tfo() functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_ctrl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/BIO_f_base64/","title":"BIO_f_base64","text":""},{"location":"man3/BIO_f_base64/#name","title":"NAME","text":"

BIO_f_base64 - base64 BIO filter

"},{"location":"man3/BIO_f_base64/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_base64(void);\n
"},{"location":"man3/BIO_f_base64/#description","title":"DESCRIPTION","text":"

BIO_f_base64() returns the base64 BIO method. This is a filter BIO that base64 encodes any data written through it and decodes any data read through it.

Base64 BIOs do not support BIO_gets() or BIO_puts().

For writing, by default output is divided to lines of length 64 characters and there is a newline at the end of output. This behavior can be changed with BIO_FLAGS_BASE64_NO_NL flag.

For reading, the first line of base64 content should be at most 1024 bytes long including newline unless the flag BIO_FLAGS_BASE64_NO_NL is set. Subsequent input lines can be of any length (i.e., newlines may appear anywhere in the input) and a newline at the end of input is not needed.

Also when reading, unless the flag BIO_FLAGS_BASE64_NO_NL is set, initial lines that contain non-base64 content (whitespace is tolerated and ignored) are skipped, as are lines longer than 1024 bytes. Decoding starts with the first line that is shorter than 1024 bytes (including the newline) and consists of only (at least one) valid base64 characters plus optional whitespace. Decoding stops when base64 padding is encountered, a soft end-of-input character (-, see EVP_DecodeUpdate(3)) occurs as the first byte after a complete group of 4 valid base64 characters is decoded, or when an error occurs (e.g. due to input characters other than valid base64 or whitespace).

If decoding stops as a result of an error, the first BIO_read(3) that returns no decoded data will typically return a negative result, rather than 0 (which indicates normal end of input). However, a negative return value can also occur if the underlying BIO supports retries, see BIO_should_read(3) and BIO_set_mem_eof_return(3).

BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used to flush the final block through the BIO.

The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags(). For writing, it causes all data to be written on one line without newline at the end. For reading, it removes all expectations on newlines in the input data.

"},{"location":"man3/BIO_f_base64/#notes","title":"NOTES","text":"

Because of the format of base64 encoding the end of the encoded block cannot always be reliably determined.

"},{"location":"man3/BIO_f_base64/#return-values","title":"RETURN VALUES","text":"

BIO_f_base64() returns the base64 BIO method.

"},{"location":"man3/BIO_f_base64/#examples","title":"EXAMPLES","text":"

Base64 encode the string \"Hello World\\n\" and write the result to standard output:

BIO *bio, *b64;\nchar message[] = \"Hello World \\n\";\n\nb64 = BIO_new(BIO_f_base64());\nbio = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_push(b64, bio);\nBIO_write(b64, message, strlen(message));\nBIO_flush(b64);\n\nBIO_free_all(b64);\n

Read base64 encoded data from standard input and write the decoded data to standard output:

BIO *bio, *b64, *bio_out;\nchar inbuf[512];\nint inlen;\n\nb64 = BIO_new(BIO_f_base64());\nbio = BIO_new_fp(stdin, BIO_NOCLOSE);\nbio_out = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_push(b64, bio);\nwhile ((inlen = BIO_read(b64, inbuf, 512)) > 0)\n    BIO_write(bio_out, inbuf, inlen);\n\nBIO_flush(bio_out);\nBIO_free_all(b64);\n
"},{"location":"man3/BIO_f_base64/#bugs","title":"BUGS","text":"

The hyphen character (-) is treated as an ad hoc soft end-of-input character when it occurs at the start of a base64 group of 4 encoded characters.

This heuristic works to detect the ends of base64 blocks in PEM or multi-part MIME, provided there are no stray hyphens in the middle input. But it is just a heuristic, and sufficiently unusual input could produce unexpected results.

There should perhaps be some way of specifying a test that the BIO can perform to reliably determine EOF (for example a MIME boundary).

It may be possible for BIO_read(3) to return zero, rather than -1, even if an error has been detected, more tests are needed to cover all the potential error paths.

"},{"location":"man3/BIO_f_base64/#see-also","title":"SEE ALSO","text":"

BIO_read(3), BIO_should_read(3), BIO_set_mem_eof_return(3), EVP_DecodeUpdate(3).

"},{"location":"man3/BIO_f_base64/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/BIO_f_buffer/","title":"BIO_f_buffer","text":""},{"location":"man3/BIO_f_buffer/#name","title":"NAME","text":"

BIO_get_buffer_num_lines, BIO_set_read_buffer_size, BIO_set_write_buffer_size, BIO_set_buffer_size, BIO_set_buffer_read_data, BIO_f_buffer - buffering BIO

"},{"location":"man3/BIO_f_buffer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_buffer(void);\n\nlong BIO_get_buffer_num_lines(BIO *b);\nlong BIO_set_read_buffer_size(BIO *b, long size);\nlong BIO_set_write_buffer_size(BIO *b, long size);\nlong BIO_set_buffer_size(BIO *b, long size);\nlong BIO_set_buffer_read_data(BIO *b, void *buf, long num);\n
"},{"location":"man3/BIO_f_buffer/#description","title":"DESCRIPTION","text":"

BIO_f_buffer() returns the buffering BIO method.

Data written to a buffering BIO is buffered and periodically written to the next BIO in the chain. Data read from a buffering BIO comes from an internal buffer which is filled from the next BIO in the chain. Both BIO_gets() and BIO_puts() are supported.

Calling BIO_reset() on a buffering BIO clears any buffered data.

BIO_get_buffer_num_lines() returns the number of lines currently buffered.

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() set the read, write or both read and write buffer sizes to size. The initial buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared when the buffer is resized.

BIO_set_buffer_read_data() clears the read buffer and fills it with num bytes of buf. If num is larger than the current buffer size the buffer is expanded.

"},{"location":"man3/BIO_f_buffer/#notes","title":"NOTES","text":"

These functions, other than BIO_f_buffer(), are implemented as macros.

Buffering BIOs implement BIO_read_ex() and BIO_gets() by using BIO_read_ex() operations on the next BIO in the chain and storing the result in an internal buffer, from which bytes are given back to the caller as appropriate for the call; a BIO_gets() is guaranteed to give the caller a whole line, and BIO_read_ex() is guaranteed to give the caller the number of bytes it asks for, unless there's an error or end of communication is reached in the next BIO. By prepending a buffering BIO to a chain it is therefore possible to provide BIO_gets() or exact size BIO_read_ex() functionality if the following BIOs do not support it.

Do not add more than one BIO_f_buffer() to a BIO chain. The result of doing so will force a full read of the size of the internal buffer of the top BIO_f_buffer(), which is 4 KiB at a minimum.

Data is only written to the next BIO in the chain when the write buffer fills or when BIO_flush() is called. It is therefore important to call BIO_flush() whenever any pending data should be written such as when removing a buffering BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate source/sink BIO is non blocking.

"},{"location":"man3/BIO_f_buffer/#return-values","title":"RETURN VALUES","text":"

BIO_f_buffer() returns the buffering BIO method.

BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0) or a negative value in case of errors.

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() return 1 if the buffer was successfully resized or <=0 for failure.

BIO_set_buffer_read_data() returns 1 if the data was set correctly or <=0 if there was an error.

"},{"location":"man3/BIO_f_buffer/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_reset(3), BIO_flush(3), BIO_pop(3), BIO_ctrl(3).

"},{"location":"man3/BIO_f_buffer/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BIO_f_cipher/","title":"BIO_f_cipher","text":""},{"location":"man3/BIO_f_cipher/#name","title":"NAME","text":"

BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter

"},{"location":"man3/BIO_f_cipher/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_cipher(void);\nint BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,\n                   const unsigned char *key, const unsigned char *iv, int enc);\nint BIO_get_cipher_status(BIO *b);\nint BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx);\n
"},{"location":"man3/BIO_f_cipher/#description","title":"DESCRIPTION","text":"

BIO_f_cipher() returns the cipher BIO method. This is a filter BIO that encrypts any data written through it, and decrypts any data read from it. It is a BIO wrapper for the cipher routines EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().

Cipher BIOs do not support BIO_gets() or BIO_puts().

BIO_flush() on an encryption BIO that is being written through is used to signal that no more data is to be encrypted: this is used to flush and possibly pad the final block through the BIO.

BIO_set_cipher() sets the cipher of BIO b to cipher using key key and IV iv. enc should be set to 1 for encryption and zero for decryption.

When reading from an encryption BIO the final block is automatically decrypted and checked when EOF is detected. BIO_get_cipher_status() is a BIO_ctrl() macro which can be called to determine whether the decryption operation was successful.

BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal BIO cipher context. The retrieved context can be used in conjunction with the standard cipher routines to set it up. This is useful when BIO_set_cipher() is not flexible enough for the applications needs.

"},{"location":"man3/BIO_f_cipher/#notes","title":"NOTES","text":"

When encrypting BIO_flush() must be called to flush the final block through the BIO. If it is not then the final block will fail a subsequent decrypt.

When decrypting an error on the final block is signaled by a zero return value from the read operation. A successful decrypt followed by EOF will also return zero for the final read. BIO_get_cipher_status() should be called to determine if the decrypt was successful.

As always, if BIO_gets() or BIO_puts() support is needed then it can be achieved by preceding the cipher BIO with a buffering BIO.

"},{"location":"man3/BIO_f_cipher/#return-values","title":"RETURN VALUES","text":"

BIO_f_cipher() returns the cipher BIO method.

BIO_set_cipher() returns 1 for success and 0 for failure.

BIO_get_cipher_status() returns 1 for a successful decrypt and <=0 for failure.

BIO_get_cipher_ctx() returns 1 for success and <=0 for failure.

"},{"location":"man3/BIO_f_cipher/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BIO_f_md/","title":"BIO_f_md","text":""},{"location":"man3/BIO_f_md/#name","title":"NAME","text":"

BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter

"},{"location":"man3/BIO_f_md/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_md(void);\nint BIO_set_md(BIO *b, EVP_MD *md);\nint BIO_get_md(BIO *b, EVP_MD **mdp);\nint BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);\n
"},{"location":"man3/BIO_f_md/#description","title":"DESCRIPTION","text":"

BIO_f_md() returns the message digest BIO method. This is a filter BIO that digests any data passed through it. It is a BIO wrapper for the digest routines EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal().

Any data written or read through a digest BIO using BIO_read_ex() and BIO_write_ex() is digested.

BIO_gets(), if its size parameter is large enough finishes the digest calculation and returns the digest value. BIO_puts() is not supported.

BIO_reset() reinitialises a digest BIO.

BIO_set_md() sets the message digest of BIO b to md: this must be called to initialize a digest BIO before any data is passed through it. It is a BIO_ctrl() macro.

BIO_get_md() places a pointer to the digest BIOs digest method in mdp. It is a BIO_ctrl() macro.

BIO_get_md_ctx() returns the digest BIOs context into mdcp.

"},{"location":"man3/BIO_f_md/#notes","title":"NOTES","text":"

The context returned by BIO_get_md_ctx() can be used in calls to EVP_DigestFinal() and also the signature routines EVP_SignFinal() and EVP_VerifyFinal().

The context returned by BIO_get_md_ctx() is an internal context structure. Changes made to this context will affect the digest BIO itself and the context pointer will become invalid when the digest BIO is freed.

After the digest has been retrieved from a digest BIO it must be reinitialized by calling BIO_reset(), or BIO_set_md() before any more data is passed through it.

If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this can be done by prepending a buffering BIO.

Calling BIO_get_md_ctx() will return the context and initialize the BIO state. This allows applications to initialize the context externally if the standard calls such as BIO_set_md() are not sufficiently flexible.

"},{"location":"man3/BIO_f_md/#return-values","title":"RETURN VALUES","text":"

BIO_f_md() returns the digest BIO method.

BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and <=0 for failure.

"},{"location":"man3/BIO_f_md/#examples","title":"EXAMPLES","text":"

The following example creates a BIO chain containing an SHA1 and MD5 digest BIO and passes the string \"Hello World\" through it. Error checking has been omitted for clarity.

BIO *bio, *mdtmp;\nchar message[] = \"Hello World\";\n\nbio = BIO_new(BIO_s_null());\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_sha1());\n/*\n * For BIO_push() we want to append the sink BIO and keep a note of\n * the start of the chain.\n */\nbio = BIO_push(mdtmp, bio);\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_md5());\nbio = BIO_push(mdtmp, bio);\n/* Note: mdtmp can now be discarded */\nBIO_write(bio, message, strlen(message));\n

The next example digests data by reading through a chain instead:

BIO *bio, *mdtmp;\nchar buf[1024];\nint rdlen;\n\nbio = BIO_new_file(file, \"rb\");\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_sha1());\nbio = BIO_push(mdtmp, bio);\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_md5());\nbio = BIO_push(mdtmp, bio);\ndo {\n    rdlen = BIO_read(bio, buf, sizeof(buf));\n    /* Might want to do something with the data here */\n} while (rdlen > 0);\n

This next example retrieves the message digests from a BIO chain and outputs them. This could be used with the examples above.

BIO *mdtmp;\nunsigned char mdbuf[EVP_MAX_MD_SIZE];\nint mdlen;\nint i;\n\nmdtmp = bio;   /* Assume bio has previously been set up */\ndo {\n    EVP_MD *md;\n\n    mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);\n    if (!mdtmp)\n        break;\n    BIO_get_md(mdtmp, &md);\n    printf(\"%s digest\", OBJ_nid2sn(EVP_MD_get_type(md)));\n    mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);\n    for (i = 0; i < mdlen; i++) printf(\":%02X\", mdbuf[i]);\n    printf(\"\\n\");\n    mdtmp = BIO_next(mdtmp);\n} while (mdtmp);\n\nBIO_free_all(bio);\n
"},{"location":"man3/BIO_f_md/#bugs","title":"BUGS","text":"

The lack of support for BIO_puts() and the non standard behaviour of BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() and BIO_puts() should be passed to the next BIO in the chain and digest the data passed through and that digests should be retrieved using a separate BIO_ctrl() call.

"},{"location":"man3/BIO_f_md/#history","title":"HISTORY","text":"

Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the BIO was initialized first.

"},{"location":"man3/BIO_f_md/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BIO_f_null/","title":"BIO_f_null","text":""},{"location":"man3/BIO_f_null/#name","title":"NAME","text":"

BIO_f_null - null filter

"},{"location":"man3/BIO_f_null/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_null(void);\n
"},{"location":"man3/BIO_f_null/#description","title":"DESCRIPTION","text":"

BIO_f_null() returns the null filter BIO method. This is a filter BIO that does nothing.

All requests to a null filter BIO are passed through to the next BIO in the chain: this means that a BIO chain containing a null filter BIO behaves just as though the BIO was not there.

"},{"location":"man3/BIO_f_null/#notes","title":"NOTES","text":"

As may be apparent a null filter BIO is not particularly useful.

"},{"location":"man3/BIO_f_null/#return-values","title":"RETURN VALUES","text":"

BIO_f_null() returns the null filter BIO method.

"},{"location":"man3/BIO_f_null/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/BIO_f_prefix/","title":"BIO_f_prefix","text":""},{"location":"man3/BIO_f_prefix/#name","title":"NAME","text":"

BIO_f_prefix, BIO_set_prefix, BIO_set_indent, BIO_get_indent - prefix BIO filter

"},{"location":"man3/BIO_f_prefix/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_prefix(void);\nlong BIO_set_prefix(BIO *b, const char *prefix);\nlong BIO_set_indent(BIO *b, long indent);\nlong BIO_get_indent(BIO *b);\n
"},{"location":"man3/BIO_f_prefix/#description","title":"DESCRIPTION","text":"

BIO_f_cipher() returns the prefix BIO method. This is a filter for text output, where each line gets automatically prefixed and indented according to user input.

The prefix and the indentation are combined. For each line of output going through this filter, the prefix is output first, then the amount of additional spaces indicated by the indentation, and then the line itself.

By default, there is no prefix, and indentation is set to 0.

BIO_set_prefix() sets the prefix to be used for future lines of text, using prefix. prefix may be NULL, signifying that there should be no prefix. If prefix isn't NULL, this function makes a copy of it.

BIO_set_indent() sets the indentation to be used for future lines of text, using indent. Negative values are not allowed.

BIO_get_indent() gets the current indentation.

"},{"location":"man3/BIO_f_prefix/#notes","title":"NOTES","text":"

BIO_set_prefix(), BIO_set_indent() and BIO_get_indent() are implemented as macros.

"},{"location":"man3/BIO_f_prefix/#return-values","title":"RETURN VALUES","text":"

BIO_f_prefix() returns the prefix BIO method.

BIO_set_prefix() returns 1 if the prefix was correctly set, or <=0 on failure.

BIO_set_indent() returns 1 if the prefix was correctly set, or <=0 on failure.

BIO_get_indent() returns the current indentation, or a negative value for failure.

"},{"location":"man3/BIO_f_prefix/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_f_prefix/#copyright","title":"COPYRIGHT","text":"

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.

"},{"location":"man3/BIO_f_readbuffer/","title":"BIO_f_readbuffer","text":""},{"location":"man3/BIO_f_readbuffer/#name","title":"NAME","text":"

BIO_f_readbuffer - read only buffering BIO that supports BIO_tell() and BIO_seek()

"},{"location":"man3/BIO_f_readbuffer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_readbuffer(void);\n
"},{"location":"man3/BIO_f_readbuffer/#description","title":"DESCRIPTION","text":"

BIO_f_readbuffer() returns the read buffering BIO method.

This BIO filter can be inserted on top of BIO's that do not support BIO_tell() or BIO_seek() (e.g. A file BIO that uses stdin).

Data read from a read buffering BIO comes from an internal buffer which is filled from the next BIO in the chain.

BIO_gets() is supported for read buffering BIOs. Writing data to a read buffering BIO is not supported.

Calling BIO_reset() on a read buffering BIO does not clear any buffered data.

"},{"location":"man3/BIO_f_readbuffer/#notes","title":"NOTES","text":"

Read buffering BIOs implement BIO_read_ex() by using BIO_read_ex() operations on the next BIO (e.g. a file BIO) in the chain and storing the result in an internal buffer, from which bytes are given back to the caller as appropriate for the call. BIO_read_ex() is guaranteed to give the caller the number of bytes it asks for, unless there's an error or end of communication is reached in the next BIO. The internal buffer can grow to cache the entire contents of the next BIO in the chain. BIO_seek() uses the internal buffer, so that it can only seek into data that is already read.

"},{"location":"man3/BIO_f_readbuffer/#return-values","title":"RETURN VALUES","text":"

BIO_f_readbuffer() returns the read buffering BIO method.

"},{"location":"man3/BIO_f_readbuffer/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_read(3), BIO_gets(3), BIO_reset(3), BIO_ctrl(3).

"},{"location":"man3/BIO_f_readbuffer/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/BIO_f_ssl/","title":"BIO_f_ssl","text":""},{"location":"man3/BIO_f_ssl/#name","title":"NAME","text":"

BIO_do_handshake, BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO

"},{"location":"man3/BIO_f_ssl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/ssl.h>\n\nconst BIO_METHOD *BIO_f_ssl(void);\n\nlong BIO_set_ssl(BIO *b, SSL *ssl, long c);\nlong BIO_get_ssl(BIO *b, SSL **sslp);\nlong BIO_set_ssl_mode(BIO *b, long client);\nlong BIO_set_ssl_renegotiate_bytes(BIO *b, long num);\nlong BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);\nlong BIO_get_num_renegotiates(BIO *b);\n\nBIO *BIO_new_ssl(SSL_CTX *ctx, int client);\nBIO *BIO_new_ssl_connect(SSL_CTX *ctx);\nBIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);\nint BIO_ssl_copy_session_id(BIO *to, BIO *from);\nvoid BIO_ssl_shutdown(BIO *bio);\n\nlong BIO_do_handshake(BIO *b);\n
"},{"location":"man3/BIO_f_ssl/#description","title":"DESCRIPTION","text":"

BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a wrapper round the OpenSSL SSL routines adding a BIO \"flavour\" to SSL I/O.

I/O performed on an SSL BIO communicates using the SSL protocol with the SSLs read and write BIOs. If an SSL connection is not established then an attempt is made to establish one on the first I/O call.

If a BIO is appended to an SSL BIO using BIO_push() it is automatically used as the SSL BIOs read and write BIOs.

Calling BIO_reset() on an SSL BIO closes down any current SSL connection by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in the chain: this will typically disconnect the underlying transport. The SSL BIO is then reset to the initial accept or connect state.

If the close flag is set when an SSL BIO is freed then the internal SSL structure is also freed using SSL_free().

BIO_set_ssl() sets the internal SSL pointer of SSL BIO b to ssl using the close flag c.

BIO_get_ssl() retrieves the SSL pointer of SSL BIO b, it can then be manipulated using the standard SSL library functions.

BIO_set_ssl_mode() sets the SSL BIO mode to client. If client is 1 client mode is set. If client is 0 server mode is set.

BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count of SSL BIO b to num. When set after every num bytes of I/O (read and write) the SSL session is automatically renegotiated. num must be at least 512 bytes.

BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout of SSL BIO b to seconds. When the renegotiate timeout elapses the session is automatically renegotiated.

BIO_get_num_renegotiates() returns the total number of session renegotiations due to I/O or timeout of SSL BIO b.

BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client mode if client is non zero.

BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a connect BIO.

BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a buffering BIO, an SSL BIO (using ctx), and a connect BIO.

BIO_ssl_copy_session_id() copies an SSL session id between BIO chains from and to. It does this by locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer.

BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It does this by locating the SSL BIO in the chain and calling SSL_shutdown() on its internal SSL pointer.

BIO_do_handshake() attempts to complete an SSL handshake on the supplied BIO and establish the SSL connection. For non-SSL BIOs the connection is done typically at TCP level. If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. The call BIO_should_retry() should be used for nonblocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect.

"},{"location":"man3/BIO_f_ssl/#notes","title":"NOTES","text":"

SSL BIOs are exceptional in that if the underlying transport is non blocking they can still request a retry in exceptional circumstances. Specifically this will happen if a session renegotiation takes place during a BIO_read_ex() operation, one case where this happens is when step up occurs.

The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That is when this flag is set an SSL BIO using a blocking transport will never request a retry.

Since unknown BIO_ctrl() operations are sent through filter BIOs the servers name and port can be set using BIO_set_host() on the BIO returned by BIO_new_ssl_connect() without having to locate the connect BIO first.

Applications do not have to call BIO_do_handshake() but may wish to do so to separate the handshake process from other I/O processing.

BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.

BIO_ssl_copy_session_id() is not currently supported on QUIC SSL objects and fails if called on such an object.

"},{"location":"man3/BIO_f_ssl/#return-values","title":"RETURN VALUES","text":"

BIO_f_ssl() returns the SSL BIO_METHOD structure.

BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on success or a value which is less than or equal to 0 if an error occurred.

BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return a valid BIO structure on success or NULL if an error occurred.

BIO_ssl_copy_session_id() returns 1 on success or 0 on error, or if called on a QUIC SSL object.

BIO_do_handshake() returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established.

"},{"location":"man3/BIO_f_ssl/#examples","title":"EXAMPLES","text":"

This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the unencrypted example in BIO_s_connect(3).

BIO *sbio, *out;\nint len;\nchar tmpbuf[1024];\nSSL_CTX *ctx;\nSSL *ssl;\n\n/* XXX Seed the PRNG if needed. */\n\nctx = SSL_CTX_new(TLS_client_method());\n\n/* XXX Set verify paths and mode here. */\n\nsbio = BIO_new_ssl_connect(ctx);\nBIO_get_ssl(sbio, &ssl);\nif (ssl == NULL) {\n    fprintf(stderr, \"Can't locate SSL pointer\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX We might want to do other things with ssl here */\n\n/* An empty host part means the loopback address */\nBIO_set_conn_hostname(sbio, \":https\");\n\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\nif (BIO_do_connect(sbio) <= 0) {\n    fprintf(stderr, \"Error connecting to server\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX Could examine ssl here to get connection info */\n\nBIO_puts(sbio, \"GET / HTTP/1.0\\n\\n\");\nfor (;;) {\n    len = BIO_read(sbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(out, tmpbuf, len);\n}\nBIO_free_all(sbio);\nBIO_free(out);\n

Here is a simple server example. It makes use of a buffering BIO to allow lines to be read from the SSL BIO using BIO_gets. It creates a pseudo web page containing the actual request from a client and also echoes the request to standard output.

BIO *sbio, *bbio, *acpt, *out;\nint len;\nchar tmpbuf[1024];\nSSL_CTX *ctx;\nSSL *ssl;\n\n/* XXX Seed the PRNG if needed. */\n\nctx = SSL_CTX_new(TLS_server_method());\nif (!SSL_CTX_use_certificate_file(ctx, \"server.pem\", SSL_FILETYPE_PEM)\n        || !SSL_CTX_use_PrivateKey_file(ctx, \"server.pem\", SSL_FILETYPE_PEM)\n        || !SSL_CTX_check_private_key(ctx)) {\n    fprintf(stderr, \"Error setting up SSL_CTX\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX Other things like set verify locations, EDH temp callbacks. */\n\n/* New SSL BIO setup as server */\nsbio = BIO_new_ssl(ctx, 0);\nBIO_get_ssl(sbio, &ssl);\nif (ssl == NULL) {\n    fprintf(stderr, \"Can't locate SSL pointer\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\nbbio = BIO_new(BIO_f_buffer());\nsbio = BIO_push(bbio, sbio);\nacpt = BIO_new_accept(\"4433\");\n\n/*\n * By doing this when a new connection is established\n * we automatically have sbio inserted into it. The\n * BIO chain is now 'swallowed' by the accept BIO and\n * will be freed when the accept BIO is freed.\n */\nBIO_set_accept_bios(acpt, sbio);\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\n\n/* First call to BIO_do_accept() sets up accept BIO */\nif (BIO_do_accept(acpt) <= 0) {\n    fprintf(stderr, \"Error setting up accept BIO\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

/* Second call to BIO_do_accept() waits for incoming connection */ if (BIO_do_accept(acpt) <= 0) { fprintf(stderr, \"Error accepting connection\\n\"); ERR_print_errors_fp(stderr); exit(1); }

/* We only want one connection so remove and free accept BIO */\nsbio = BIO_pop(acpt);\nBIO_free_all(acpt);\n\nif (BIO_do_handshake(sbio) <= 0) {\n    fprintf(stderr, \"Error in SSL handshake\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\nBIO_puts(sbio, \"HTTP/1.0 200 OK\\r\\nContent-type: text/plain\\r\\n\\r\\n\");\nBIO_puts(sbio, \"\\r\\nConnection Established\\r\\nRequest headers:\\r\\n\");\nBIO_puts(sbio, \"--------------------------------------------------\\r\\n\");\n\nfor (;;) {\n    len = BIO_gets(sbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(sbio, tmpbuf, len);\n    BIO_write(out, tmpbuf, len);\n    /* Look for blank line signifying end of headers*/\n    if (tmpbuf[0] == '\\r' || tmpbuf[0] == '\\n')\n        break;\n}\n\nBIO_puts(sbio, \"--------------------------------------------------\\r\\n\");\nBIO_puts(sbio, \"\\r\\n\");\nBIO_flush(sbio);\nBIO_free_all(sbio);\n
"},{"location":"man3/BIO_f_ssl/#history","title":"HISTORY","text":"

In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, the I/O BIO reference count was incorrectly incremented (instead of decremented) and dissociated with the SSL BIO even if the SSL BIO was not explicitly being popped (e.g. a pop higher up the chain). Applications which included workarounds for this bug (e.g. freeing BIOs more than once) should be modified to handle this fix or they may free up an already freed BIO.

"},{"location":"man3/BIO_f_ssl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/BIO_find_type/","title":"BIO_find_type","text":""},{"location":"man3/BIO_find_type/#name","title":"NAME","text":"

BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal

"},{"location":"man3/BIO_find_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_find_type(BIO *b, int bio_type);\nBIO *BIO_next(BIO *b);\nint BIO_method_type(const BIO *b);\n
"},{"location":"man3/BIO_find_type/#description","title":"DESCRIPTION","text":"

The BIO_find_type() searches for a BIO of a given type in a chain, starting at BIO b. If type is a specific type (such as BIO_TYPE_MEM) then a search is made for a BIO of that type. If type is a general type (such as BIO_TYPE_SOURCE_SINK) then the next matching BIO of the given general type is searched for. BIO_find_type() returns the next matching BIO or NULL if none is found. If type is BIO_TYPE_NONE it will not find a match.

The following general types are defined: BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER, and BIO_TYPE_SOURCE_SINK.

For a list of the specific types, see the <openssl/bio.h> header file.

BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs in a chain or used in conjunction with BIO_find_type() to find all BIOs of a certain type.

BIO_method_type() returns the type of a BIO.

"},{"location":"man3/BIO_find_type/#return-values","title":"RETURN VALUES","text":"

BIO_find_type() returns a matching BIO or NULL for no match.

BIO_next() returns the next BIO in a chain.

BIO_method_type() returns the type of the BIO b.

"},{"location":"man3/BIO_find_type/#examples","title":"EXAMPLES","text":"

Traverse a chain looking for digest BIOs:

BIO *btmp;\n\nbtmp = in_bio; /* in_bio is chain to search through */\ndo {\n    btmp = BIO_find_type(btmp, BIO_TYPE_MD);\n    if (btmp == NULL)\n        break; /* Not found */\n    /* btmp is a digest BIO, do something with it ...*/\n    ...\n\n    btmp = BIO_next(btmp);\n} while (btmp);\n
"},{"location":"man3/BIO_find_type/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/BIO_get_data/","title":"BIO_get_data","text":""},{"location":"man3/BIO_get_data/#name","title":"NAME","text":"

BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown, BIO_get_shutdown - functions for managing BIO state information

"},{"location":"man3/BIO_get_data/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nvoid BIO_set_data(BIO *a, void *ptr);\nvoid *BIO_get_data(BIO *a);\nvoid BIO_set_init(BIO *a, int init);\nint BIO_get_init(BIO *a);\nvoid BIO_set_shutdown(BIO *a, int shut);\nint BIO_get_shutdown(BIO *a);\n
"},{"location":"man3/BIO_get_data/#description","title":"DESCRIPTION","text":"

These functions are mainly useful when implementing a custom BIO.

The BIO_set_data() function associates the custom data pointed to by ptr with the BIO. This data can subsequently be retrieved via a call to BIO_get_data(). This can be used by custom BIOs for storing implementation specific information.

The BIO_set_init() function sets the value of the BIO's \"init\" flag to indicate whether initialisation has been completed for this BIO or not. A nonzero value indicates that initialisation is complete, whilst zero indicates that it is not. Often initialisation will complete during initial construction of the BIO. For some BIOs however, initialisation may not complete until after additional steps have occurred (for example through calling custom ctrls). The BIO_get_init() function returns the value of the \"init\" flag.

The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource is also closed when the BIO is freed.

"},{"location":"man3/BIO_get_data/#return-values","title":"RETURN VALUES","text":"

BIO_get_data() returns a pointer to the implementation specific custom data associated with this BIO, or NULL if none has been set.

BIO_get_init() returns the state of the BIO's init flag.

BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.

"},{"location":"man3/BIO_get_data/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_meth_new(3)

"},{"location":"man3/BIO_get_data/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_get_data/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/BIO_get_ex_new_index/","title":"BIO_get_ex_new_index","text":""},{"location":"man3/BIO_get_ex_new_index/#name","title":"NAME","text":"

BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, BIO_set_app_data, BIO_get_app_data, DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data, RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, RSA_set_app_data, RSA_get_app_data, SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, SSL_set_app_data, SSL_get_app_data, SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data, SSL_CTX_set_app_data, SSL_CTX_get_app_data, SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data, SSL_SESSION_set_app_data, SSL_SESSION_get_app_data, UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, UI_set_app_data, UI_get_app_data, X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data, X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data - application-specific data

"},{"location":"man3/BIO_get_ex_new_index/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nint TYPE_get_ex_new_index(long argl, void *argp,\n                          CRYPTO_EX_new *new_func,\n                          CRYPTO_EX_dup *dup_func,\n                          CRYPTO_EX_free *free_func);\n\nint TYPE_set_ex_data(TYPE *d, int idx, void *arg);\n\nvoid *TYPE_get_ex_data(const TYPE *d, int idx);\n\n#define TYPE_set_app_data(TYPE *d, void *arg)\n#define TYPE_get_app_data(TYPE *d)\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                        CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint DH_set_ex_data(DH *type, int idx, void *arg);\nvoid *DH_get_ex_data(DH *type, int idx);\nint DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint DSA_set_ex_data(DSA *type, int idx, void *arg);\nvoid *DSA_get_ex_data(DSA *type, int idx);\nint EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint EC_KEY_set_ex_data(EC_KEY *type, int idx, void *arg);\nvoid *EC_KEY_get_ex_data(EC_KEY *type, int idx);\nint RSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint RSA_set_ex_data(RSA *type, int idx, void *arg);\nvoid *RSA_get_ex_data(RSA *type, int idx);\nint RSA_set_app_data(RSA *type, void *arg);\nvoid *RSA_get_app_data(RSA *type);\nint ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);\nvoid *ENGINE_get_ex_data(ENGINE *type, int idx);\n
"},{"location":"man3/BIO_get_ex_new_index/#description","title":"DESCRIPTION","text":"

In the description here, TYPE is used a placeholder for any of the OpenSSL datatypes listed in CRYPTO_get_ex_new_index(3).

All functions with a TYPE of DH, DSA, RSA and EC_KEY are deprecated. Applications should instead use EVP_PKEY_set_ex_data(), EVP_PKEY_get_ex_data() and EVP_PKEY_get_ex_new_index().

All functions with a TYPE of ENGINE are deprecated. Applications using engines should be replaced by providers.

These functions handle application-specific data for OpenSSL data structures.

TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index() with the correct index value.

TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with an offset into the opaque exdata part of the TYPE object. d MUST NOT be NULL.

TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an offset into the opaque exdata part of the TYPE object. d MUST NOT be NULL.

For compatibility with previous releases, the exdata index of zero is reserved for \"application data.\" There are two convenience functions for this. TYPE_set_app_data() is a macro that invokes TYPE_set_ex_data() with idx set to zero. TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with idx set to zero.

"},{"location":"man3/BIO_get_ex_new_index/#return-values","title":"RETURN VALUES","text":"

TYPE_get_ex_new_index() returns a new index on success or -1 on error.

TYPE_set_ex_data() returns 1 on success or 0 on error.

TYPE_get_ex_data() returns the application data or NULL if an error occurred.

"},{"location":"man3/BIO_get_ex_new_index/#see-also","title":"SEE ALSO","text":"

CRYPTO_get_ex_new_index(3).

"},{"location":"man3/BIO_get_ex_new_index/#history","title":"HISTORY","text":"

The functions DH_get_ex_new_index(), DH_set_ex_data(), DH_get_ex_data(), DSA_get_ex_new_index(), DSA_set_ex_data(), DSA_get_ex_data(), EC_KEY_get_ex_new_index(), EC_KEY_set_ex_data(), EC_KEY_get_ex_data(), ENGINE_get_ex_new_index(), ENGINE_set_ex_data(), ENGINE_get_ex_data(), RSA_get_ex_new_index(), RSA_set_ex_data(), RSA_get_ex_data(), RSA_set_app_data() and RSA_get_app_data() were deprecated in OpenSSL 3.0.

"},{"location":"man3/BIO_get_ex_new_index/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 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.

"},{"location":"man3/BIO_get_rpoll_descriptor/","title":"BIO_get_rpoll_descriptor","text":""},{"location":"man3/BIO_get_rpoll_descriptor/#name","title":"NAME","text":"

BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor - obtain a structure which can be used to determine when a BIO object can next be read or written

"},{"location":"man3/BIO_get_rpoll_descriptor/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef struct bio_poll_descriptor_st {\n    uint32_t type;\n    union {\n        int        fd;\n        void       *custom;\n        uintptr_t  custom_ui;\n    } value;\n} BIO_POLL_DESCRIPTOR;\n\nint BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);\nint BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);\n
"},{"location":"man3/BIO_get_rpoll_descriptor/#description","title":"DESCRIPTION","text":"

BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill *desc with a poll descriptor. A poll descriptor is a tagged union structure which represents some kind of OS or non-OS resource which can be used to synchronise on I/O availability events.

BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor() outputs a descriptor which can be used to determine when the BIO can (potentially) next be written.

It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() to output the same descriptor.

Poll descriptors can represent different kinds of information. A typical kind of resource which might be represented by a poll descriptor is an OS file descriptor which can be used with APIs such as select().

The kinds of poll descriptor defined by OpenSSL are:

Because poll descriptors are a tagged union structure, they can represent different kinds of information. New types of poll descriptor may be defined, including by applications, according to their needs.

"},{"location":"man3/BIO_get_rpoll_descriptor/#return-values","title":"RETURN VALUES","text":"

The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 on success and 0 on failure.

These functions are permitted to succeed and initialise *desc with a poll descriptor of type BIO_POLL_DESCRIPTOR_TYPE_NONE to indicate that the BIO is not pollable for readability or writeability respectively.

"},{"location":"man3/BIO_get_rpoll_descriptor/#see-also","title":"SEE ALSO","text":"

SSL_handle_events(3), SSL_get_event_timeout(3), SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3), bio(7)

"},{"location":"man3/BIO_get_rpoll_descriptor/#history","title":"HISTORY","text":"

The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_get_rpoll_descriptor/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2023 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.

"},{"location":"man3/BIO_meth_new/","title":"BIO_meth_new","text":""},{"location":"man3/BIO_meth_new/#name","title":"NAME","text":"

BIO_get_new_index, BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg - Routines to build up BIO methods

"},{"location":"man3/BIO_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_get_new_index(void);\n\nBIO_METHOD *BIO_meth_new(int type, const char *name);\n\nvoid BIO_meth_free(BIO_METHOD *biom);\n\nint (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,\n                                               size_t *);\nint (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);\nint BIO_meth_set_write_ex(BIO_METHOD *biom,\n                          int (*bwrite)(BIO *, const char *, size_t, size_t *));\nint BIO_meth_set_write(BIO_METHOD *biom,\n                       int (*write)(BIO *, const char *, int));\n\nint (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);\nint (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);\nint BIO_meth_set_read_ex(BIO_METHOD *biom,\n                         int (*bread)(BIO *, char *, size_t, size_t *));\nint BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));\n\nint (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);\nint BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));\n\nint (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);\nint BIO_meth_set_gets(BIO_METHOD *biom,\n                      int (*gets)(BIO *, char *, int));\n\nlong (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);\nint BIO_meth_set_ctrl(BIO_METHOD *biom,\n                      long (*ctrl)(BIO *, int, long, void *));\n\nint (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);\nint BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));\n\nint (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);\nint BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));\n\nlong (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);\nint BIO_meth_set_callback_ctrl(BIO_METHOD *biom,\n                               long (*callback_ctrl)(BIO *, int, BIO_info_cb *));\n\nossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,\n                                                              BIO_MSG *,\n                                                              size_t,\n                                                              size_t,\n                                                              uint64_t);\nint BIO_meth_set_sendmmsg(BIO_METHOD *biom,\n                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,\n                                             size_t, uint64_t));\n\nossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,\n                                                              BIO_MSG *,\n                                                              size_t,\n                                                              size_t,\n                                                              uint64_t);\nint BIO_meth_set_recvmmsg(BIO_METHOD *biom,\n                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,\n                                             size_t, uint64_t));\n
"},{"location":"man3/BIO_meth_new/#description","title":"DESCRIPTION","text":"

The BIO_METHOD type is a structure used for the implementation of new BIO types. It provides a set of functions used by OpenSSL for the implementation of the various BIO capabilities. See the bio(7) page for more information.

BIO_meth_new() creates a new BIO_METHOD structure that contains a type identifier type and a string that represents its name. type can be set to either BIO_TYPE_NONE or via BIO_get_new_index() if a unique type is required for searching (See BIO_find_type(3))

Note that BIO_get_new_index() can only be used 127 times before it returns an error.

The set of standard OpenSSL provided BIO types is provided in <openssl/bio.h>. Some examples include BIO_TYPE_BUFFER and BIO_TYPE_CIPHER. Filter BIOs should have a type which have the \"filter\" bit set (BIO_TYPE_FILTER). Source/sink BIOs should have the \"source/sink\" bit set (BIO_TYPE_SOURCE_SINK). File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the \"descriptor\" bit set (BIO_TYPE_DESCRIPTOR). See the BIO_find_type(3) page for more information.

BIO_meth_free() destroys a BIO_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function used for writing arbitrary length data to the BIO respectively. This function will be called in response to the application calling BIO_write_ex() or BIO_write(). The parameters for the function have the same meaning as for BIO_write_ex(). Older code may call BIO_meth_get_write() and BIO_meth_set_write() instead. Applications should not call both BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write() when the function was set with BIO_meth_set_write_ex().

BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used for reading arbitrary length data from the BIO respectively. This function will be called in response to the application calling BIO_read_ex() or BIO_read(). The parameters for the function have the same meaning as for BIO_read_ex(). Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead. Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read() or call BIO_meth_get_read() when the function was set with BIO_meth_set_read_ex().

BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for writing a NULL terminated string to the BIO respectively. This function will be called in response to the application calling BIO_puts(). The parameters for the function have the same meaning as for BIO_puts().

BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically used for reading a line of data from the BIO respectively (see the BIO_gets(3) page for more information). This function will be called in response to the application calling BIO_gets(). The parameters for the function have the same meaning as for BIO_gets().

BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for processing ctrl messages in the BIO respectively. See the BIO_ctrl(3) page for more information. This function will be called in response to the application calling BIO_ctrl(). The parameters for the function have the same meaning as for BIO_ctrl().

BIO_meth_get_create() and BIO_meth_set_create() get and set the function used for creating a new instance of the BIO respectively. This function will be called in response to the application calling BIO_new() and passing in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the memory for the new BIO, and a pointer to this newly allocated structure will be passed as a parameter to the function. If a create function is set, BIO_new() will not mark the BIO as initialised on allocation. BIO_set_init(3) must then be called either by the create function, or later, by a BIO ctrl function, once BIO initialisation is complete.

BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used for destroying an instance of a BIO respectively. This function will be called in response to the application calling BIO_free(). A pointer to the BIO to be destroyed is passed as a parameter. The destroy function should be used for BIO specific clean up. The memory for the BIO itself should not be freed by this function.

BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the function used for processing callback ctrl messages in the BIO respectively. See the BIO_callback_ctrl(3) page for more information. This function will be called in response to the application calling BIO_callback_ctrl(). The parameters for the function have the same meaning as for BIO_callback_ctrl().

BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() get and set the functions used for handling BIO_sendmmsg() and BIO_recvmmsg() calls respectively. See BIO_sendmmsg(3) for more information.

"},{"location":"man3/BIO_meth_new/#return-values","title":"RETURN VALUES","text":"

BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.

BIO_meth_new(int type, const char *name) returns a valid BIO_METHOD or NULL if an error occurred.

The BIO_meth_set functions return 1 on success or 0 on error.

The BIO_meth_get functions return the corresponding function pointers.

"},{"location":"man3/BIO_meth_new/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_find_type(3), BIO_ctrl(3), BIO_read_ex(3), BIO_new(3)

"},{"location":"man3/BIO_meth_new/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/BIO_new/","title":"BIO_new","text":""},{"location":"man3/BIO_new/#name","title":"NAME","text":"

BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions

"},{"location":"man3/BIO_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type);\nBIO *BIO_new(const BIO_METHOD *type);\nint BIO_up_ref(BIO *a);\nint BIO_free(BIO *a);\nvoid BIO_vfree(BIO *a);\nvoid BIO_free_all(BIO *a);\n
"},{"location":"man3/BIO_new/#description","title":"DESCRIPTION","text":"

The BIO_new_ex() function returns a new BIO using method type associated with the library context libctx (see OSSL_LIB_CTX(3)). The library context may be NULL to indicate the default library context. type MUST NOT be NULL.

The BIO_new() is the same as BIO_new_ex() except the default library context is always used.

BIO_up_ref() increments the reference count associated with the BIO object.

BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO but it does not return a value. If a is NULL nothing is done. Calling BIO_free() may also have some effect on the underlying I/O structure, for example it may close the file being referred to under certain circumstances. For more details see the individual BIO_METHOD descriptions.

BIO_free_all() frees up an entire BIO chain, it does not halt if an error occurs freeing up an individual BIO in the chain. If a is NULL nothing is done.

"},{"location":"man3/BIO_new/#return-values","title":"RETURN VALUES","text":"

BIO_new_ex() and BIO_new() return a newly created BIO or NULL if the call fails.

BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.

BIO_free_all() and BIO_vfree() do not return values.

"},{"location":"man3/BIO_new/#notes","title":"NOTES","text":"

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.

"},{"location":"man3/BIO_new/#history","title":"HISTORY","text":"

BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.

BIO_new_ex() was added in OpenSSL 3.0.

"},{"location":"man3/BIO_new/#examples","title":"EXAMPLES","text":"

Create a memory BIO:

BIO *mem = BIO_new(BIO_s_mem());\n
"},{"location":"man3/BIO_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BIO_new_CMS/","title":"BIO_new_CMS","text":""},{"location":"man3/BIO_new_CMS/#name","title":"NAME","text":"

BIO_new_CMS - CMS streaming filter BIO

"},{"location":"man3/BIO_new_CMS/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nBIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);\n
"},{"location":"man3/BIO_new_CMS/#description","title":"DESCRIPTION","text":"

BIO_new_CMS() returns a streaming filter BIO chain based on cms. The output of the filter is written to out. Any data written to the chain is automatically translated to a BER format CMS structure of the appropriate type.

"},{"location":"man3/BIO_new_CMS/#notes","title":"NOTES","text":"

The chain returned by this function behaves like a standard filter BIO. It supports non blocking I/O. Content is processed and streamed on the fly and not all held in memory at once: so it is possible to encode very large structures. After all content has been written through the chain BIO_flush() must be called to finalise the structure.

The CMS_STREAM flag must be included in the corresponding flags parameter of the cms creation function.

If an application wishes to write additional data to out BIOs should be removed from the chain using BIO_pop() and freed with BIO_free() until out is reached. If no additional data needs to be written BIO_free_all() can be called to free up the whole chain.

Any content written through the filter is used verbatim: no canonical translation is performed.

It is possible to chain multiple BIOs to, for example, create a triple wrapped signed, enveloped, signed structure. In this case it is the applications responsibility to set the inner content type of any outer CMS_ContentInfo structures.

Large numbers of small writes through the chain should be avoided as this will produce an output consisting of lots of OCTET STRING structures. Prepending a BIO_f_buffer() buffering BIO will prevent this.

"},{"location":"man3/BIO_new_CMS/#bugs","title":"BUGS","text":"

There is currently no corresponding inverse BIO: i.e. one which can decode a CMS structure on the fly.

"},{"location":"man3/BIO_new_CMS/#return-values","title":"RETURN VALUES","text":"

BIO_new_CMS() returns a BIO chain when successful or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/BIO_new_CMS/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_encrypt(3)

"},{"location":"man3/BIO_new_CMS/#history","title":"HISTORY","text":"

The BIO_new_CMS() function was added in OpenSSL 1.0.0.

"},{"location":"man3/BIO_new_CMS/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/BIO_parse_hostserv/","title":"BIO_parse_hostserv","text":""},{"location":"man3/BIO_parse_hostserv/#name","title":"NAME","text":"

BIO_hostserv_priorities, BIO_parse_hostserv - utility routines to parse a standard host and service string

"},{"location":"man3/BIO_parse_hostserv/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nenum BIO_hostserv_priorities {\n    BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV\n};\nint BIO_parse_hostserv(const char *hostserv, char **host, char **service,\n                       enum BIO_hostserv_priorities hostserv_prio);\n
"},{"location":"man3/BIO_parse_hostserv/#description","title":"DESCRIPTION","text":"

BIO_parse_hostserv() will parse the information given in hostserv, create strings with the hostname and service name and give those back via host and service. Those will need to be freed after they are used. hostserv_prio helps determine if hostserv shall be interpreted primarily as a hostname or a service name in ambiguous cases.

The syntax the BIO_parse_hostserv() recognises is:

host + ':' + service\nhost + ':' + '*'\nhost + ':'\n       ':' + service\n'*'  + ':' + service\nhost\nservice\n

The host part can be a name or an IP address. If it's a IPv6 address, it MUST be enclosed in brackets, such as '[::1]'.

The service part can be a service name or its port number. A service name will be mapped to a port number using the system function getservbyname().

The returned values will depend on the given hostserv string and hostserv_prio, as follows:

host + ':' + service  => *host = \"host\", *service = \"service\"\nhost + ':' + '*'      => *host = \"host\", *service = NULL\nhost + ':'            => *host = \"host\", *service = NULL\n       ':' + service  => *host = NULL, *service = \"service\"\n '*' + ':' + service  => *host = NULL, *service = \"service\"\n\nin case no ':' is present in the string, the result depends on\nhostserv_prio, as follows:\n\nwhen hostserv_prio == BIO_PARSE_PRIO_HOST\nhost                 => *host = \"host\", *service untouched\n\nwhen hostserv_prio == BIO_PARSE_PRIO_SERV\nservice              => *host untouched, *service = \"service\"\n
"},{"location":"man3/BIO_parse_hostserv/#return-values","title":"RETURN VALUES","text":"

BIO_parse_hostserv() returns 1 on success or 0 on error.

"},{"location":"man3/BIO_parse_hostserv/#see-also","title":"SEE ALSO","text":"

BIO_ADDRINFO(3)

"},{"location":"man3/BIO_parse_hostserv/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 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.

"},{"location":"man3/BIO_printf/","title":"BIO_printf","text":""},{"location":"man3/BIO_printf/#name","title":"NAME","text":"

BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf - formatted output to a BIO

"},{"location":"man3/BIO_printf/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_printf(BIO *bio, const char *format, ...);\nint BIO_vprintf(BIO *bio, const char *format, va_list args);\n\nint BIO_snprintf(char *buf, size_t n, const char *format, ...);\nint BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args);\n
"},{"location":"man3/BIO_printf/#description","title":"DESCRIPTION","text":"

BIO_printf() is similar to the standard C printf() function, except that the output is sent to the specified BIO, bio, rather than standard output. All common format specifiers are supported.

BIO_vprintf() is similar to the vprintf() function found on many platforms, the output is sent to the specified BIO, bio, rather than standard output. All common format specifiers are supported. The argument list args is a stdarg argument list.

BIO_snprintf() is for platforms that do not have the common snprintf() function. It is like sprintf() except that the size parameter, n, specifies the size of the output buffer.

BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf().

"},{"location":"man3/BIO_printf/#return-values","title":"RETURN VALUES","text":"

All functions return the number of bytes written, or -1 on error. For BIO_snprintf() and BIO_vsnprintf() this includes when the output buffer is too small.

"},{"location":"man3/BIO_printf/#notes","title":"NOTES","text":"

Except when n is 0, both BIO_snprintf() and BIO_vsnprintf() always terminate their output with '\\0'. This includes cases where -1 is returned, such as when there is insufficient space to output the whole string.

"},{"location":"man3/BIO_printf/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2021 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.

"},{"location":"man3/BIO_push/","title":"BIO_push","text":""},{"location":"man3/BIO_push/#name","title":"NAME","text":"

BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain

"},{"location":"man3/BIO_push/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_push(BIO *b, BIO *next);\nBIO *BIO_pop(BIO *b);\nvoid BIO_set_next(BIO *b, BIO *next);\n
"},{"location":"man3/BIO_push/#description","title":"DESCRIPTION","text":"

BIO_push() pushes b on next. If b is NULL the function does nothing and returns next. Otherwise it prepends b, which may be a single BIO or a chain of BIOs, to next (unless next is NULL). It then makes a control call on b and returns b.

BIO_pop() removes the BIO b from any chain is is part of. If b is NULL the function does nothing and returns NULL. Otherwise it makes a control call on b and returns the next BIO in the chain, or NULL if there is no next BIO. The removed BIO becomes a single BIO with no association with the original chain, it can thus be freed or be made part of a different chain.

BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to by next. The new chain may include some of the same BIOs from the old chain or it may be completely different.

"},{"location":"man3/BIO_push/#notes","title":"NOTES","text":"

The names of these functions are perhaps a little misleading. BIO_push() joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, the deleted BIO does not need to be at the end of a chain.

The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences (a control call is made to the affected BIOs). Any effects will be noted in the descriptions of individual BIOs.

"},{"location":"man3/BIO_push/#return-values","title":"RETURN VALUES","text":"

BIO_push() returns the head of the chain, which usually is b, or next if b is NULL.

BIO_pop() returns the next BIO in the chain, or NULL if there is no next BIO.

"},{"location":"man3/BIO_push/#examples","title":"EXAMPLES","text":"

For these examples suppose md1 and md2 are digest BIOs, b64 is a base64 BIO and f is a file BIO.

If the call:

BIO_push(b64, f);\n

is made then the new chain will be b64-f. After making the calls

BIO_push(md2, b64);\nBIO_push(md1, md2);\n

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, base64 encoded, and finally written to f.

It should be noted that reading causes data to pass in the reverse direction, that is data is read from f, base64 decoded, and digested by md2 and then md1.

The call:

BIO_pop(md2);\n

will return b64 and the new chain will be md1-b64-f. Data can be written to and read from md1 as before, except that md2 will no more be applied.

"},{"location":"man3/BIO_push/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_push/#history","title":"HISTORY","text":"

The BIO_set_next() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_push/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BIO_read/","title":"BIO_read","text":""},{"location":"man3/BIO_read/#name","title":"NAME","text":"

BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_get_line, BIO_puts - BIO I/O functions

"},{"location":"man3/BIO_read/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);\nint BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);\n\nint BIO_read(BIO *b, void *data, int dlen);\nint BIO_gets(BIO *b, char *buf, int size);\nint BIO_get_line(BIO *b, char *buf, int size);\nint BIO_write(BIO *b, const void *data, int dlen);\nint BIO_puts(BIO *b, const char *buf);\n
"},{"location":"man3/BIO_read/#description","title":"DESCRIPTION","text":"

BIO_read_ex() attempts to read dlen bytes from BIO b and places the data in data. If any bytes were successfully read then the number of bytes read is stored in *readbytes.

BIO_write_ex() attempts to write dlen bytes from data to BIO b. If successful then the number of bytes written is stored in *written unless written is NULL.

BIO_read() attempts to read len bytes from BIO b and places the data in buf.

BIO_gets() performs the BIOs \"gets\" operation and places the data in buf. Usually this operation will attempt to read a line of data from the BIO of maximum length size-1. There are exceptions to this, however; for example, BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all. The returned string is always NUL-terminated and the '\\n' is preserved if present in the input data. On binary input there may be NUL characters within the string; in this case the return value (if nonnegative) may give an incorrect length.

BIO_get_line() attempts to read from BIO b a line of data up to the next '\\n' or the maximum length size-1 is reached and places the data in buf. The returned string is always NUL-terminated and the '\\n' is preserved if present in the input data. On binary input there may be NUL characters within the string; in this case the return value (if nonnegative) gives the actual length read. For implementing this, unfortunately the data needs to be read byte-by-byte.

BIO_write() attempts to write len bytes from buf to BIO b.

BIO_puts() attempts to write a NUL-terminated string buf to BIO b.

"},{"location":"man3/BIO_read/#return-values","title":"RETURN VALUES","text":"

BIO_read_ex() returns 1 if data was successfully read, and 0 otherwise.

BIO_write_ex() returns 1 if no error was encountered writing data, 0 otherwise. Requesting to write 0 bytes is not considered an error.

BIO_write() returns -2 if the \"write\" operation is not implemented by the BIO or -1 on other errors. Otherwise it returns the number of bytes written. This may be 0 if the BIO b is NULL or dlen <= 0.

BIO_gets() returns -2 if the \"gets\" operation is not implemented by the BIO or -1 on other errors. Otherwise it typically returns the amount of data read, but depending on the implementation it may return only the length up to the first NUL character contained in the data read. In any case the trailing NUL that is added after the data read is not included in the length returned.

All other functions return either the amount of data successfully read or written (if the return value is positive) or that no data was successfully read or written if the result is 0 or -1. If the return value is -2 then the operation is not implemented in the specific BIO type.

"},{"location":"man3/BIO_read/#notes","title":"NOTES","text":"

A 0 or -1 return is not necessarily an indication of an error. In particular when the source/sink is nonblocking or of a certain type it may merely be an indication that no data is currently available and that the application should retry the operation later.

One technique sometimes used with blocking sockets is to use a system call (such as select(), poll() or equivalent) to determine when data is available and then call read() to read the data. The equivalent with BIOs (that is call select() on the underlying I/O structure and then call BIO_read() to read the data) should not be used because a single call to BIO_read() can cause several reads (and writes in the case of SSL BIOs) on the underlying I/O structure and may block as a result. Instead select() (or equivalent) should be combined with non blocking I/O so successive reads will request a retry instead of blocking.

See BIO_should_retry(3) for details of how to determine the cause of a retry and other I/O issues.

If the \"gets\" method is not supported by a BIO then BIO_get_line() can be used. It is also possible to make BIO_gets() usable even if the \"gets\" method is not supported by adding a buffering BIO BIO_f_buffer(3) to the chain.

"},{"location":"man3/BIO_read/#see-also","title":"SEE ALSO","text":"

BIO_should_retry(3)

"},{"location":"man3/BIO_read/#history","title":"HISTORY","text":"

BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO did not keep the '\\n' at the end of the line in the buffer.

BIO_get_line() was added in OpenSSL 3.0.

BIO_write_ex() returns 1 if the size of the data to write is 0 and the written parameter of the function can be NULL since OpenSSL 3.0.

"},{"location":"man3/BIO_read/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/BIO_s_accept/","title":"BIO_s_accept","text":""},{"location":"man3/BIO_s_accept/#name","title":"NAME","text":"

BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios, BIO_get_peer_name, BIO_get_peer_port, BIO_get_accept_ip_family, BIO_set_accept_ip_family, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO

"},{"location":"man3/BIO_s_accept/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_accept(void);\n\nlong BIO_set_accept_name(BIO *b, char *name);\nchar *BIO_get_accept_name(BIO *b);\n\nlong BIO_set_accept_port(BIO *b, char *port);\nchar *BIO_get_accept_port(BIO *b);\n\nBIO *BIO_new_accept(char *host_port);\n\nlong BIO_set_nbio_accept(BIO *b, int n);\nlong BIO_set_tfo_accept(BIO *b, int n);\nlong BIO_set_accept_bios(BIO *b, char *bio);\n\nchar *BIO_get_peer_name(BIO *b);\nchar *BIO_get_peer_port(BIO *b);\nlong BIO_get_accept_ip_family(BIO *b);\nlong BIO_set_accept_ip_family(BIO *b, long family);\n\nlong BIO_set_bind_mode(BIO *b, long mode);\nlong BIO_get_bind_mode(BIO *b);\n\nint BIO_do_accept(BIO *b);\n
"},{"location":"man3/BIO_s_accept/#description","title":"DESCRIPTION","text":"

BIO_s_accept() returns the accept BIO method. This is a wrapper round the platform's TCP/IP socket accept routines.

Using accept BIOs, TCP/IP connections can be accepted and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.

Read and write operations on an accept BIO will perform I/O on the underlying connection. If no connection is established and the port (see below) is set up properly then the BIO waits for an incoming connection.

Accept BIOs support BIO_puts() but not BIO_gets().

If the close flag is set on an accept BIO then any active connection on that chain is shutdown and the socket closed when the BIO is freed.

Calling BIO_reset() on an accept BIO will close any active connection and reset the BIO into a state where it awaits another incoming connection.

BIO_get_fd() and BIO_set_fd() can be called to retrieve or set the accept socket. See BIO_s_fd(3)

BIO_set_accept_name() uses the string name to set the accept name. The name is represented as a string of the form \"host:port\", where \"host\" is the interface to use and \"port\" is the port. The host can be \"*\" or empty which is interpreted as meaning any interface. If the host is an IPv6 address, it has to be enclosed in brackets, for example \"[::1]:https\". \"port\" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table.

BIO_set_accept_port() uses the string port to set the accept port of BIO b. \"port\" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table. If the given port is 0 then a random available port is chosen. It may be queried using BIO_sock_info() and BIO_ADDR_service_string(3).

BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into a single call: that is it creates a new accept BIO with port host_port.

BIO_set_nbio_accept() sets the accept socket to blocking mode (the default) if n is 0 or non blocking mode if n is 1.

BIO_set_tfo_accept() enables TCP Fast Open on the accept socket if n is 1 or disables TCP Fast Open if n is 0 (the default). Setting the value to 1 is equivalent to setting BIO_SOCK_TFO in BIO_set_bind_mode().

BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the chain when an incoming connection is received. This is useful if, for example, a buffering or SSL BIO is required for each connection. The chain of BIOs must not be freed after this call, they will be automatically freed when the accept BIO is freed.

BIO_get_accept_ip_family() returns the IP family accepted by the BIO b, which may be BIO_FAMILY_IPV4, BIO_FAMILY_IPV6, or BIO_FAMILY_IPANY.

BIO_set_accept_ip_family() sets the IP family family accepted by BIO b. The default is BIO_FAMILY_IPANY.

BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the current bind mode. If BIO_BIND_NORMAL (the default) is set then another socket cannot be bound to the same port. If BIO_BIND_REUSEADDR is set then other sockets can bind to the same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and attempt is first made to use BIO_BIN_NORMAL, if this fails and the port is not in use then a second attempt is made using BIO_BIND_REUSEADDR. If BIO_SOCK_TFO is set, then the socket will be configured to accept TCP Fast Open connections.

BIO_do_accept() serves two functions. When it is first called, after the accept BIO has been setup, it will attempt to create the accept socket and bind an address to it. Second and subsequent calls to BIO_do_accept() will await an incoming connection, or request a retry in non blocking mode.

"},{"location":"man3/BIO_s_accept/#notes","title":"NOTES","text":"

When an accept BIO is at the end of a chain it will await an incoming connection before processing I/O calls. When an accept BIO is not at then end of a chain it passes I/O calls to the next BIO in the chain.

When a connection is established a new socket BIO is created for the connection and appended to the chain. That is the chain is now accept->socket. This effectively means that attempting I/O on an initial accept socket will await an incoming connection then perform I/O on it.

If any additional BIOs have been set using BIO_set_accept_bios() then they are placed between the socket and the accept BIO, that is the chain will be accept->otherbios->socket.

If a server wishes to process multiple connections (as is normally the case) then the accept BIO must be made available for further incoming connections. This can be done by waiting for a connection and then calling:

connection = BIO_pop(accept);\n

After this call connection will contain a BIO for the recently established connection and accept will now be a single BIO again which can be used to await further incoming connections. If no further connections will be accepted the accept can be freed using BIO_free().

If only a single connection will be processed it is possible to perform I/O using the accept BIO itself. This is often undesirable however because the accept BIO will still accept additional incoming connections. This can be resolved by using BIO_pop() (see above) and freeing up the accept BIO after the initial connection.

If the underlying accept socket is nonblocking and BIO_do_accept() is called to await an incoming connection it is possible for BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens then it is an indication that an accept attempt would block: the application should take appropriate action to wait until the underlying socket has accepted a connection and retry the call.

BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_get_peer_name(), BIO_get_peer_port(), BIO_get_accept_ip_family(), BIO_set_accept_ip_family(), BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.

"},{"location":"man3/BIO_s_accept/#return-values","title":"RETURN VALUES","text":"

BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode() return 1 for success and <= 0 for failure.

BIO_get_accept_name() returns the accept name or NULL on error. BIO_get_peer_name() returns the peer name or NULL on error.

BIO_get_accept_port() returns the accept port as a string or NULL on error. BIO_get_peer_port() returns the peer port as a string or NULL on error. BIO_get_accept_ip_family() returns the IP family or <= 0 on error.

BIO_get_bind_mode() returns the set of BIO_BIND flags, or <= 0 on failure.

BIO_new_accept() returns a BIO or NULL on error.

"},{"location":"man3/BIO_s_accept/#examples","title":"EXAMPLES","text":"

This example accepts two connections on port 4444, sends messages down each and finally closes both down.

BIO *abio, *cbio, *cbio2;\n\n/* First call to BIO_do_accept() sets up accept BIO */\nabio = BIO_new_accept(\"4444\");\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error setting up accept\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* Wait for incoming connection */\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error accepting connection\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nfprintf(stderr, \"Connection 1 established\\n\");\n\n/* Retrieve BIO for connection */\ncbio = BIO_pop(abio);\nBIO_puts(cbio, \"Connection 1: Sending out Data on initial connection\\n\");\nfprintf(stderr, \"Sent out data on connection 1\\n\");\n\n/* Wait for another connection */\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error accepting connection\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nfprintf(stderr, \"Connection 2 established\\n\");\n\n/* Close accept BIO to refuse further connections */\ncbio2 = BIO_pop(abio);\nBIO_free(abio);\nBIO_puts(cbio2, \"Connection 2: Sending out Data on second\\n\");\nfprintf(stderr, \"Sent out data on connection 2\\n\");\n\nBIO_puts(cbio, \"Connection 1: Second connection established\\n\");\n\n/* Close the two established connections */\nBIO_free(cbio);\nBIO_free(cbio2);\n
"},{"location":"man3/BIO_s_accept/#history","title":"HISTORY","text":"

BIO_set_tfo_accept() was added in OpenSSL 3.2.

"},{"location":"man3/BIO_s_accept/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/BIO_s_bio/","title":"BIO_s_bio","text":""},{"location":"man3/BIO_s_bio/#name","title":"NAME","text":"

BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO

"},{"location":"man3/BIO_s_bio/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_bio(void);\n\nint BIO_make_bio_pair(BIO *b1, BIO *b2);\nint BIO_destroy_bio_pair(BIO *b);\nint BIO_shutdown_wr(BIO *b);\n\nint BIO_set_write_buf_size(BIO *b, long size);\nsize_t BIO_get_write_buf_size(BIO *b, long size);\n\nint BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);\n\nint BIO_get_write_guarantee(BIO *b);\nsize_t BIO_ctrl_get_write_guarantee(BIO *b);\nint BIO_get_read_request(BIO *b);\nsize_t BIO_ctrl_get_read_request(BIO *b);\nint BIO_ctrl_reset_read_request(BIO *b);\n
"},{"location":"man3/BIO_s_bio/#description","title":"DESCRIPTION","text":"

BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink BIOs where data written to either half of the pair is buffered and can be read from the other half. Both halves must usually by handled by the same application thread since no locking is done on the internal data structures.

Since BIO chains typically end in a source/sink BIO it is possible to make this one half of a BIO pair and have all the data processed by the chain under application control.

One typical use of BIO pairs is to place TLS/SSL I/O under application control, this can be used when the application wishes to use a non standard transport for TLS/SSL or the normal socket routines are inappropriate.

Calls to BIO_read_ex() will read data from the buffer or request a retry if no data is available.

Calls to BIO_write_ex() will place data in the buffer or request a retry if the buffer is full.

The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to determine the amount of pending data in the read or write buffer.

BIO_reset() clears any data in the write buffer.

BIO_make_bio_pair() joins two separate BIOs into a connected pair.

BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association.

BIO_shutdown_wr() is used to close down a BIO b. After this call no further writes on BIO b are allowed (they will return an error). Reads on the other half of the pair will return any pending data or EOF when all pending data has been read.

BIO_set_write_buf_size() sets the write buffer size of BIO b to size. If the size is not initialized a default value is used. This is currently 17K, sufficient for a maximum size TLS record.

BIO_get_write_buf_size() returns the size of the write buffer.

BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and BIO_set_write_buf_size() to create a connected pair of BIOs bio1, bio2 with write buffer sizes writebuf1 and writebuf2. If either size is zero then the default size is used. BIO_new_bio_pair() does not check whether bio1 or bio2 do point to some other BIO, the values are overwritten, BIO_free() is not called.

BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum length of data that can be currently written to the BIO. Writes larger than this value will return a value from BIO_write_ex() less than the amount requested or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function whereas BIO_get_write_guarantee() is a macro.

BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data requested, or the buffer size if it is less, if the last read attempt at the other half of the BIO pair failed due to an empty buffer. This can be used to determine how much data should be written to the BIO so the next read will succeed: this is most useful in TLS/SSL applications where the amount of data read is usually meaningful rather than just a buffer size. After a successful read this call will return zero. It also will return zero once new data has been written satisfying the read request or part of it. Note that BIO_get_read_request() never returns an amount larger than that returned by BIO_get_write_guarantee().

BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to zero.

"},{"location":"man3/BIO_s_bio/#notes","title":"NOTES","text":"

Both halves of a BIO pair should be freed. That is even if one half is implicit freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.

When used in bidirectional applications (such as TLS/SSL) care should be taken to flush any data in the write buffer. This can be done by calling BIO_pending() on the other half of the pair and, if any data is pending, reading it and sending it to the underlying transport. This must be done before any normal processing (such as calling select() ) due to a request and BIO_should_read() being true.

To see why this is important consider a case where a request is sent using BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be true. If the application then waits for data to be available on the underlying transport before flushing the write buffer it will never succeed because the request was never sent!

BIO_eof() is true if no data is in the peer BIO and the peer BIO has been shutdown.

BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), BIO_set_write_buf_size(), BIO_get_write_buf_size(), BIO_get_write_guarantee(), and BIO_get_read_request() are implemented as macros.

"},{"location":"man3/BIO_s_bio/#return-values","title":"RETURN VALUES","text":"

BIO_new_bio_pair() returns 1 on success, with the new BIOs available in bio1 and bio2, or 0 on failure, with NULL pointers stored into the locations for bio1 and bio2. Check the error stack for more information.

[XXXXX: More return values need to be added here]

"},{"location":"man3/BIO_s_bio/#examples","title":"EXAMPLES","text":"

The BIO pair can be used to have full control over the network access of an application. The application can call select() on the socket as required without having to go through the SSL-interface.

BIO *internal_bio, *network_bio;\n\n...\nBIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);\nSSL_set_bio(ssl, internal_bio, internal_bio);\nSSL_operations(); /* e.g. SSL_read and SSL_write */\n...\n\napplication |   TLS-engine\n   |        |\n   +----------> SSL_operations()\n            |     /\\    ||\n            |     ||    \\/\n            |   BIO-pair (internal_bio)\n            |   BIO-pair (network_bio)\n            |     ||     /\\\n            |     \\/     ||\n   +-----------< BIO_operations()\n   |        |\n   |        |\n  socket\n\n ...\n SSL_free(ssl);                /* implicitly frees internal_bio */\n BIO_free(network_bio);\n ...\n

As the BIO pair will only buffer the data and never directly access the connection, it behaves nonblocking and will return as soon as the write buffer is full or the read buffer is drained. Then the application has to flush the write buffer and/or fill the read buffer.

Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO and must be transferred to the network. Use BIO_ctrl_get_read_request() to find out, how many bytes must be written into the buffer before the SSL_operation() can successfully be continued.

"},{"location":"man3/BIO_s_bio/#warnings","title":"WARNINGS","text":"

As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ condition, but there is still data in the write buffer. An application must not rely on the error value of SSL_operation() but must assure that the write buffer is always flushed first. Otherwise a deadlock may occur as the peer might be waiting for the data before being able to continue.

"},{"location":"man3/BIO_s_bio/#see-also","title":"SEE ALSO","text":"

SSL_set_bio(3), ssl(7), bio(7), BIO_should_retry(3), BIO_read_ex(3)

"},{"location":"man3/BIO_s_bio/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BIO_s_connect/","title":"BIO_s_connect","text":""},{"location":"man3/BIO_s_connect/#name","title":"NAME","text":"

BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_address, BIO_set_conn_ip_family, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_address, BIO_get_conn_ip_family, BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio, BIO_do_connect - connect BIO

"},{"location":"man3/BIO_s_connect/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_connect(void);\n\nBIO *BIO_new_connect(const char *name);\n\nlong BIO_set_conn_hostname(BIO *b, char *name);\nlong BIO_set_conn_port(BIO *b, char *port);\nlong BIO_set_conn_address(BIO *b, BIO_ADDR *addr);\nlong BIO_set_conn_ip_family(BIO *b, long family);\nconst char *BIO_get_conn_hostname(BIO *b);\nconst char *BIO_get_conn_port(BIO *b);\nconst BIO_ADDR *BIO_get_conn_address(BIO *b);\nconst long BIO_get_conn_ip_family(BIO *b);\n\nlong BIO_set_nbio(BIO *b, long n);\n\nint BIO_set_sock_type(BIO *b, int sock_type);\nint BIO_get_sock_type(BIO *b);\nint BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);\n\nlong BIO_do_connect(BIO *b);\n
"},{"location":"man3/BIO_s_connect/#description","title":"DESCRIPTION","text":"

BIO_s_connect() returns the connect BIO method. This is a wrapper round the platform's TCP/IP socket connection routines.

Using connect BIOs, TCP/IP connections can be made and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.

Read and write operations on a connect BIO will perform I/O on the underlying connection. If no connection is established and the port and hostname (see below) is set up properly then a connection is established first.

Connect BIOs support BIO_puts() and BIO_gets().

If the close flag is set on a connect BIO then any active connection is shutdown and the socket closed when the BIO is freed.

Calling BIO_reset() on a connect BIO will close any active connection and reset the BIO into a state where it can connect to the same host again.

BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a single call: that is it creates a new connect BIO with hostname name.

BIO_set_conn_hostname() uses the string name to set the hostname. The hostname can be an IP address; if the address is an IPv6 one, it must be enclosed in brackets [ and ]. The hostname can also include the port in the form hostname:port; see BIO_parse_hostserv(3) and BIO_set_conn_port() for details.

BIO_set_conn_port() sets the port to port. port can be the numerical form or a service string such as \"http\", which will be mapped to a port number using the system function getservbyname().

BIO_set_conn_address() sets the address and port information using a BIO_ADDR(3ssl).

BIO_set_conn_ip_family() sets the IP family.

BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL if the BIO is initialized but no hostname is set. This return value is an internal pointer which should not be modified.

BIO_get_conn_port() returns the port as a string. This return value is an internal pointer which should not be modified.

BIO_get_conn_address() returns the address information as a BIO_ADDR. This return value is an internal pointer which should not be modified.

BIO_get_conn_ip_family() returns the IP family of the connect BIO.

BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then blocking I/O is set. If n is 1 then non blocking I/O is set. Blocking I/O is the default. The call to BIO_set_nbio() should be made before the connection is established because non blocking I/O is set during the connect process.

BIO_do_connect() attempts to connect the supplied BIO. This performs an SSL/TLS handshake as far as supported by the BIO. For non-SSL BIOs the connection is done typically at TCP level. If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. The call BIO_should_retry() should be used for non blocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect.

BIO_set_sock_type() can be used to set a socket type value as would be passed in a call to socket(2). The only currently supported values are SOCK_STREAM (the default) and SOCK_DGRAM. If SOCK_DGRAM is configured, the connection created is a UDP datagram socket handled via BIO_s_datagram(3). I/O calls such as BIO_read(3) and BIO_write(3) are forwarded transparently to an internal BIO_s_datagram(3) instance. The created BIO_s_datagram(3) instance can be retrieved using BIO_get0_dgram_bio() if desired, which writes a pointer to the BIO_s_datagram(3) instance to *dgram_bio. The lifetime of the internal BIO_s_datagram(3) is managed by BIO_s_connect() and does not need to be freed by the caller.

BIO_get_sock_type() retrieves the value set using BIO_set_sock_type().

"},{"location":"man3/BIO_s_connect/#notes","title":"NOTES","text":"

If blocking I/O is set then a non positive return value from any I/O call is caused by an error condition, although a zero return will normally mean that the connection was closed.

If the port name is supplied as part of the hostname then this will override any value set with BIO_set_conn_port(). This may be undesirable if the application does not wish to allow connection to arbitrary ports. This can be avoided by checking for the presence of the ':' character in the passed hostname and either indicating an error or truncating the string at that point.

The values returned by BIO_get_conn_hostname(), BIO_get_conn_address(), and BIO_get_conn_port() are updated when a connection attempt is made. Before any connection attempt the values returned are those set by the application itself.

Applications do not have to call BIO_do_connect() but may wish to do so to separate the connection process from other I/O processing.

If non blocking I/O is set then retries will be requested as appropriate.

It addition to BIO_should_read() and BIO_should_write() it is also possible for BIO_should_io_special() to be true during the initial connection process with the reason BIO_RR_CONNECT. If this is returned then this is an indication that a connection attempt would block, the application should then take appropriate action to wait until the underlying socket has connected and retry the call.

BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(), BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(), BIO_set_conn_ip_family(), BIO_get_conn_ip_family(), BIO_set_nbio(), and BIO_do_connect() are macros.

"},{"location":"man3/BIO_s_connect/#return-values","title":"RETURN VALUES","text":"

BIO_s_connect() returns the connect BIO method.

BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family() return 1 or <=0 if an error occurs.

BIO_set_conn_hostname() returns 1 on success and <=0 on failure.

BIO_get_conn_address() returns the address information or NULL if none was set.

BIO_get_conn_hostname() returns the connected hostname or NULL if none was set.

BIO_get_conn_ip_family() returns the address family or -1 if none was set.

BIO_get_conn_port() returns a string representing the connected port or NULL if not set.

BIO_set_nbio() returns 1 or <=0 if an error occurs.

BIO_do_connect() returns 1 if the connection was successfully established and <=0 if the connection failed.

BIO_set_sock_type() returns 1 on success or 0 on failure.

BIO_get_sock_type() returns a socket type or 0 if the call is not supported.

BIO_get0_dgram_bio() returns 1 on success or 0 on failure.

"},{"location":"man3/BIO_s_connect/#examples","title":"EXAMPLES","text":"

This is example connects to a webserver on the local host and attempts to retrieve a page and copy the result to standard output.

BIO *cbio, *out;\nint len;\nchar tmpbuf[1024];\n\ncbio = BIO_new_connect(\"localhost:http\");\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\nif (BIO_do_connect(cbio) <= 0) {\n    fprintf(stderr, \"Error connecting to server\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nBIO_puts(cbio, \"GET / HTTP/1.0\\n\\n\");\nfor (;;) {\n    len = BIO_read(cbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(out, tmpbuf, len);\n}\nBIO_free(cbio);\nBIO_free(out);\n
"},{"location":"man3/BIO_s_connect/#see-also","title":"SEE ALSO","text":"

BIO_ADDR(3), BIO_parse_hostserv(3)

"},{"location":"man3/BIO_s_connect/#history","title":"HISTORY","text":"

BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), and BIO_get_conn_ip() were removed in OpenSSL 1.1.0. Use BIO_set_conn_address() and BIO_get_conn_address() instead.

Connect BIOs support BIO_gets() since OpenSSL 3.2.

"},{"location":"man3/BIO_s_connect/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/BIO_s_core/","title":"BIO_s_core","text":""},{"location":"man3/BIO_s_core/#name","title":"NAME","text":"

BIO_s_core, BIO_new_from_core_bio - OSSL_CORE_BIO functions

"},{"location":"man3/BIO_s_core/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_core(void);\n\nBIO *BIO_new_from_core_bio(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio);\n
"},{"location":"man3/BIO_s_core/#description","title":"DESCRIPTION","text":"

BIO_s_core() returns the core BIO method function.

A core BIO is treated as source/sink BIO which communicates to some external BIO. This is primarily useful to provider authors. A number of calls from libcrypto into a provider supply an OSSL_CORE_BIO parameter. This represents a BIO within libcrypto, but cannot be used directly by a provider. Instead it should be wrapped using a BIO_s_core().

Once a BIO is constructed based on BIO_s_core(), the associated OSSL_CORE_BIO object should be set on it using BIO_set_data(3). Note that the BIO will only operate correctly if it is associated with a library context constructed using OSSL_LIB_CTX_new_from_dispatch(3). To associate the BIO with a library context construct it using BIO_new_ex(3).

BIO_new_from_core_bio() is a convenience function that constructs a new BIO based on BIO_s_core() and that is associated with the given library context. It then also sets the OSSL_CORE_BIO object on the BIO using BIO_set_data(3).

"},{"location":"man3/BIO_s_core/#return-values","title":"RETURN VALUES","text":"

BIO_s_core() return a core BIO BIO_METHOD structure.

BIO_new_from_core_bio() returns a BIO structure on success or NULL on failure. A failure will most commonly be because the library context was not constructed using OSSL_LIB_CTX_new_from_dispatch(3).

"},{"location":"man3/BIO_s_core/#history","title":"HISTORY","text":"

BIO_s_core() and BIO_new_from_core_bio() were added in OpenSSL 3.0.

"},{"location":"man3/BIO_s_core/#examples","title":"EXAMPLES","text":"

Create a core BIO and write some data to it:

int some_function(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio) {\n    BIO *cbio = BIO_new_from_core_bio(libctx, corebio);\n\n    if (cbio == NULL)\n        return 0;\n\n    BIO_puts(cbio, \"Hello World\\n\");\n\n    BIO_free(cbio);\n    return 1;\n}\n
"},{"location":"man3/BIO_s_core/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2022 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.

"},{"location":"man3/BIO_s_datagram/","title":"BIO_s_datagram","text":""},{"location":"man3/BIO_s_datagram/#name","title":"NAME","text":"

BIO_s_datagram, BIO_new_dgram, BIO_ctrl_dgram_connect, BIO_ctrl_set_connected, BIO_dgram_recv_timedout, BIO_dgram_send_timedout, BIO_dgram_get_peer, BIO_dgram_set_peer, BIO_dgram_detect_peer_addr, BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics

"},{"location":"man3/BIO_s_datagram/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO_METHOD *BIO_s_datagram(void);\nBIO *BIO_new_dgram(int fd, int close_flag);\n\nint BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);\nint BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);\nint BIO_dgram_recv_timedout(BIO *bio);\nint BIO_dgram_send_timedout(BIO *bio);\nint BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);\nint BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);\nint BIO_dgram_get_mtu_overhead(BIO *bio);\nint BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);\n
"},{"location":"man3/BIO_s_datagram/#description","title":"DESCRIPTION","text":"

BIO_s_datagram() is a BIO implementation designed for use with network sockets which provide datagram semantics, such as UDP sockets. It is suitable for use with DTLSv1 or QUIC.

Because BIO_s_datagram() has datagram semantics, a single BIO_write() call sends a single datagram and a single BIO_read() call receives a single datagram. If the size of the buffer passed to BIO_read() is inadequate, the datagram is silently truncated.

For a memory-based BIO which provides datagram semantics identical to those of BIO_s_datagram(), see BIO_s_dgram_pair(3).

This BIO supports the BIO_sendmmsg(3) and BIO_recvmmsg(3) functions.

When using BIO_s_datagram(), it is important to note that:

Various controls are available for configuring the BIO_s_datagram() using BIO_ctrl(3):

BIO_new_dgram() is a helper function which instantiates a BIO_s_datagram() and sets the BIO to use the socket given in fd by calling BIO_set_fd().

"},{"location":"man3/BIO_s_datagram/#return-values","title":"RETURN VALUES","text":"

BIO_s_datagram() returns a BIO method.

BIO_new_dgram() returns a BIO on success and NULL on failure.

BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected() and BIO_dgram_set_peer() return 1 on success and 0 on failure.

BIO_dgram_get_peer() and BIO_dgram_detect_peer_addr() return 0 on failure and the number of bytes for the outputted address representation (a positive value) on success.

BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() return 0 or 1 depending on the circumstance; see discussion above.

BIO_dgram_get_mtu_overhead() returns a value in bytes.

"},{"location":"man3/BIO_s_datagram/#see-also","title":"SEE ALSO","text":"

BIO_sendmmsg(3), BIO_s_dgram_pair(3), DTLSv1_listen(3), bio(7)

"},{"location":"man3/BIO_s_datagram/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2023 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.

"},{"location":"man3/BIO_s_dgram_pair/","title":"BIO_s_dgram_pair","text":""},{"location":"man3/BIO_s_dgram_pair/#name","title":"NAME","text":"

BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps, BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu - datagram pair BIO

"},{"location":"man3/BIO_s_dgram_pair/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_dgram_pair(void);\n\nint BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,\n                           BIO **bio2, size_t writebuf2);\nint BIO_dgram_set_no_trunc(BIO *bio, int enable);\nint BIO_dgram_get_no_trunc(BIO *bio);\nuint32_t BIO_dgram_get_effective_caps(BIO *bio);\nuint32_t BIO_dgram_get_caps(BIO *bio);\nint BIO_dgram_set_caps(BIO *bio, uint32_t caps);\nint BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);\nunsigned int BIO_dgram_get_mtu(BIO *bio);\n
"},{"location":"man3/BIO_s_dgram_pair/#description","title":"DESCRIPTION","text":"

BIO_s_dgram_pair() returns the method for a BIO datagram pair. A BIO datagram pair is similar to a BIO pair (see BIO_s_bio(3)) but has datagram semantics. Broadly, this means that the length of the buffer passed to a write call will match that retrieved by a read call. If the buffer passed to a read call is too short, the datagram is truncated or the read fails, depending on how the BIO is configured.

The BIO datagram pair attaches certain metadata to each write, such as source and destination addresses. This information may be retrieved on read.

A typical application of a BIO datagram pair is to allow an application to keep all datagram network I/O requested by libssl under application control.

The BIO datagram pair is designed to support multithreaded use where certain restrictions are observed; see THREADING.

The BIO datagram pair allows each half of a pair to signal to the other half whether they support certain capabilities; see CAPABILITY INDICATION.

BIO_new_bio_dgram_pair() combines the calls to BIO_new(3), BIO_make_bio_pair(3) and BIO_set_write_buf_size(3) to create a connected pair of BIOs bio1, bio2 with write buffer sizes writebuf1 and writebuf2. If either size is zero then the default size is used.

BIO_make_bio_pair(3) may be used to join two datagram pair BIOs into a pair. The two BIOs must both use the method returned by BIO_s_dgram_pair() and neither of the BIOs may currently be associated in a pair.

BIO_destroy_bio_pair(3) destroys the association between two connected BIOs. Freeing either half of the pair will automatically destroy the association.

BIO_reset(3) clears any data in the write buffer of the given BIO. This means that the opposite BIO in the pair will no longer have any data waiting to be read.

The BIO maintains a fixed size internal write buffer. When the buffer is full, further writes will fail until the buffer is drained via calls to BIO_read(3). The size of the buffer can be changed using BIO_set_write_buf_size(3) and queried using BIO_get_write_buf_size(3).

Note that the write buffer is partially consumed by metadata stored internally which is attached to each datagram, such as source and destination addresses. The size of this overhead is undefined and may change between releases.

The standard BIO_ctrl_pending(3) call has modified behaviour and returns the size of the next datagram waiting to be read in bytes. An application can use this function to ensure it provides an adequate buffer to a subsequent read call. If no datagram is waiting to be read, zero is returned.

This BIO does not support sending or receiving zero-length datagrams. Passing a zero-length buffer to BIO_write is treated as a no-op.

BIO_eof(3) returns 1 only if the given BIO datagram pair BIO is not currently connected to a peer BIO.

BIO_get_write_guarantee(3) and BIO_ctrl_get_write_guarantee(3) return how large a datagram the next call to BIO_write(3) can accept. If there is not enough space in the write buffer to accept another datagram equal in size to the configured MTU, zero is returned (see below). This is intended to avoid a situation where an application attempts to read a datagram from a network intending to write it to a BIO datagram pair, but where the received datagram ends up being too large to write to the BIO datagram pair.

BIO_dgram_set_no_trunc() and BIO_ctrl_get_no_trunc() set and retrieve the truncation mode for the given half of a BIO datagram pair. When no-truncate mode is enabled, BIO_read() will fail if the buffer provided is inadequate to hold the next datagram to be read. If no-truncate mode is disabled (the default), the datagram will be silently truncated. This default behaviour maintains compatibility with the semantics of the Berkeley sockets API.

BIO_dgram_set_mtu() and BIO_dgram_get_mtu() may be used to set an informational MTU value on the BIO datagram pair. If BIO_dgram_set_mtu() is used on a BIO which is currently part of a BIO datagram pair, the MTU value is set on both halves of the pair. The value does not affect the operation of the BIO datagram pair (except for BIO_get_write_guarantee(); see above) but may be used by other code to determine a requested MTU. When a BIO datagram pair BIO is created, the MTU is set to an unspecified but valid value.

BIO_flush(3) is a no-op.

"},{"location":"man3/BIO_s_dgram_pair/#notes","title":"NOTES","text":"

The halves of a BIO datagram pair have independent lifetimes and must be separately freed.

"},{"location":"man3/BIO_s_dgram_pair/#threading","title":"THREADING","text":"

BIO_recvmmsg(3), BIO_sendmmsg(3), BIO_read(3), BIO_write(3), BIO_pending(3), BIO_get_write_guarantee(3) and BIO_flush(3) may be used by multiple threads simultaneously on the same BIO datagram pair. Specific BIO_ctrl(3) operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any other BIO_ctrl(3) operation, on either half of a BIO datagram pair while any other BIO call is also in progress to either half of the same BIO datagram pair results in undefined behaviour.

"},{"location":"man3/BIO_s_dgram_pair/#capability-indication","title":"CAPABILITY INDICATION","text":"

The BIO datagram pair can be used to enqueue datagrams which have source and destination addresses attached. It is important that the component consuming one side of a BIO datagram pair understand whether the other side of the pair will honour any source and destination addresses it attaches to each datagram. For example, if datagrams are queued with destination addresses set but simply read by simple calls to BIO_read(3), the destination addresses will be discarded.

Each half of a BIO datagram pair can have capability flags set on it which indicate whether source and destination addresses will be honoured by the reader and whether they will be provided by the writer. These capability flags should be set via a call to BIO_dgram_set_caps(), and these capabilities will be reflected in the value returned by BIO_dgram_get_effective_caps() on the opposite BIO. If necessary, the capability value previously set can be retrieved using BIO_dgram_get_caps(). Note that BIO_dgram_set_caps() on a given BIO controls the capabilities advertised to the peer, and BIO_dgram_get_effective_caps() on a given BIO determines the capabilities advertised by the peer of that BIO.

The following capabilities are available:

If a caller attempts to specify a destination address (for example, using BIO_sendmmsg(3)) and the peer has not advertised the BIO_DGRAM_CAP_HANDLES_DST_ADDR capability, the operation fails. Thus, capability negotiation is mandatory.

If a caller attempts to specify a source address when writing, or requests a destination address when receiving, and local address support has not been enabled, the operation fails; see BIO_dgram_set_local_addr_enable(3).

If a caller attempts to enable local address support using BIO_dgram_set_local_addr_enable(3) and BIO_dgram_get_local_addr_cap(3) does not return 1 (meaning that the peer has not advertised both the BIO_DGRAM_CAP_HANDLES_SRC_ADDR and the BIO_DGRAM_CAP_PROVIDES_DST_ADDR capability), the operation fails.

BIO_DGRAM_CAP_PROVIDES_SRC_ADDR and BIO_DGRAM_CAP_PROVIDES_DST_ADDR indicate that the application using that half of a BIO datagram pair promises to provide source and destination addresses respectively when writing datagrams to that half of the BIO datagram pair. However, these capability flags do not affect the behaviour of the BIO datagram pair.

"},{"location":"man3/BIO_s_dgram_pair/#return-values","title":"RETURN VALUES","text":"

BIO_new_bio_dgram_pair() returns 1 on success, with the new BIOs available in bio1 and bio2, or 0 on failure, with NULL pointers stored into the locations for bio1 and bio2. Check the error stack for more information.

BIO_dgram_set_no_trunc(), BIO_dgram_set_caps() and BIO_dgram_set_mtu() return 1 on success and 0 on failure.

BIO_dgram_get_no_trunc() returns 1 if no-truncate mode is enabled on a BIO, or 0 if no-truncate mode is not enabled or not supported on a given BIO.

BIO_dgram_get_effective_caps() and BIO_dgram_get_caps() return zero if no capabilities are supported.

BIO_dgram_get_mtu() returns the MTU value configured on the BIO, or zero if the operation is not supported.

"},{"location":"man3/BIO_s_dgram_pair/#see-also","title":"SEE ALSO","text":"

BIO_s_bio(3), bio(7)

"},{"location":"man3/BIO_s_dgram_pair/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/BIO_s_fd/","title":"BIO_s_fd","text":""},{"location":"man3/BIO_s_fd/#name","title":"NAME","text":"

BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO

"},{"location":"man3/BIO_s_fd/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_fd(void);\n\nint BIO_set_fd(BIO *b, int fd, int c);\nint BIO_get_fd(BIO *b, int *c);\n\nBIO *BIO_new_fd(int fd, int close_flag);\n
"},{"location":"man3/BIO_s_fd/#description","title":"DESCRIPTION","text":"

BIO_s_fd() returns the file descriptor BIO method. This is a wrapper round the platforms file descriptor routines such as read() and write().

BIO_read_ex() and BIO_write_ex() read or write the underlying descriptor. BIO_puts() is supported but BIO_gets() is not.

If the close flag is set then close() is called on the underlying file descriptor when the BIO is freed.

BIO_reset() attempts to change the file pointer to the start of file such as by using lseek(fd, 0, 0).

BIO_seek() sets the file pointer to position ofs from start of file such as by using lseek(fd, ofs, 0).

BIO_tell() returns the current file position such as by calling lseek(fd, 0, 1).

BIO_set_fd() sets the file descriptor of BIO b to fd and the close flag to c.

BIO_get_fd() places the file descriptor of BIO b in c if it is not NULL. It also returns the file descriptor.

BIO_new_fd() returns a file descriptor BIO using fd and close_flag.

"},{"location":"man3/BIO_s_fd/#notes","title":"NOTES","text":"

The behaviour of BIO_read_ex() and BIO_write_ex() depends on the behavior of the platforms read() and write() calls on the descriptor. If the underlying file descriptor is in a non blocking mode then the BIO will behave in the manner described in the BIO_read_ex(3) and BIO_should_retry(3) manual pages.

File descriptor BIOs should not be used for socket I/O. Use socket BIOs instead.

BIO_set_fd() and BIO_get_fd() are implemented as macros.

"},{"location":"man3/BIO_s_fd/#return-values","title":"RETURN VALUES","text":"

BIO_s_fd() returns the file descriptor BIO method.

BIO_set_fd() returns 1 on success or <=0 for failure.

BIO_get_fd() returns the file descriptor or -1 if the BIO has not been initialized. It also returns zero and negative values if other error occurs.

BIO_new_fd() returns the newly allocated BIO or NULL is an error occurred.

"},{"location":"man3/BIO_s_fd/#examples","title":"EXAMPLES","text":"

This is a file descriptor BIO version of \"Hello World\":

BIO *out;\n\nout = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n
"},{"location":"man3/BIO_s_fd/#see-also","title":"SEE ALSO","text":"

BIO_seek(3), BIO_tell(3), BIO_reset(3), BIO_read_ex(3), BIO_write_ex(3), BIO_puts(3), BIO_gets(3), BIO_printf(3), BIO_set_close(3), BIO_get_close(3)

"},{"location":"man3/BIO_s_fd/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BIO_s_file/","title":"BIO_s_file","text":""},{"location":"man3/BIO_s_file/#name","title":"NAME","text":"

BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, BIO_read_filename, BIO_write_filename, BIO_append_filename, BIO_rw_filename - FILE bio

"},{"location":"man3/BIO_s_file/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_file(void);\nBIO *BIO_new_file(const char *filename, const char *mode);\nBIO *BIO_new_fp(FILE *stream, int flags);\n\nBIO_set_fp(BIO *b, FILE *fp, int flags);\nBIO_get_fp(BIO *b, FILE **fpp);\n\nint BIO_read_filename(BIO *b, char *name);\nint BIO_write_filename(BIO *b, char *name);\nint BIO_append_filename(BIO *b, char *name);\nint BIO_rw_filename(BIO *b, char *name);\n
"},{"location":"man3/BIO_s_file/#description","title":"DESCRIPTION","text":"

BIO_s_file() returns the BIO file method. As its name implies it is a wrapper round the stdio FILE structure and it is a source/sink BIO.

Calls to BIO_read_ex() and BIO_write_ex() read and write data to the underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.

BIO_flush() on a file BIO calls the fflush() function on the wrapped stream.

BIO_reset() attempts to change the file pointer to the start of file using fseek(stream, 0, 0).

BIO_seek() sets the file pointer to position ofs from start of file using fseek(stream, ofs, 0).

BIO_eof() calls feof().

Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO is freed.

BIO_new_file() creates a new file BIO with mode mode the meaning of mode is the same as the stdio function fopen(). The BIO_CLOSE flag is set on the returned BIO.

BIO_new_fp() creates a file BIO wrapping stream. Flags can be: BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying stream to text mode, default is binary: this only has any effect under Win32).

BIO_set_fp() sets the fp of a file BIO to fp. flags has the same meaning as in BIO_new_fp(), it is a macro.

BIO_get_fp() retrieves the fp of a file BIO, it is a macro.

BIO_seek() is a macro that sets the position pointer to offset bytes from the start of file.

BIO_tell() returns the value of the position pointer.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() set the file BIO b to use file name for reading, writing, append or read write respectively.

"},{"location":"man3/BIO_s_file/#notes","title":"NOTES","text":"

When wrapping stdout, stdin or stderr the underlying stream should not normally be closed so the BIO_NOCLOSE flag should be set.

Because the file BIO calls the underlying stdio functions any quirks in stdio behaviour will be mirrored by the corresponding BIO.

On Windows BIO_new_files reserves for the filename argument to be UTF-8 encoded. In other words if you have to make it work in multi- lingual environment, encode filenames in UTF-8.

"},{"location":"man3/BIO_s_file/#return-values","title":"RETURN VALUES","text":"

BIO_s_file() returns the file BIO method.

BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error occurred.

BIO_set_fp() and BIO_get_fp() return 1 for success or <=0 for failure (although the current implementation never return 0).

BIO_seek() returns 0 for success or negative values for failure.

BIO_tell() returns the current file position or negative values for failure.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1 for success or <=0 for failure. An error is also returned if the file does not exist.

"},{"location":"man3/BIO_s_file/#examples","title":"EXAMPLES","text":"

File BIO \"hello world\":

BIO *bio_out;\n\nbio_out = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_printf(bio_out, \"Hello World\\n\");\n

Alternative technique:

BIO *bio_out;\n\nbio_out = BIO_new(BIO_s_file());\nif (bio_out == NULL)\n    /* Error */\nif (BIO_set_fp(bio_out, stdout, BIO_NOCLOSE) <= 0)\n    /* Error */\nBIO_printf(bio_out, \"Hello World\\n\");\n

Write to a file:

BIO *out;\n\nout = BIO_new_file(\"filename.txt\", \"w\");\nif (!out)\n    /* Error */\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n

Alternative technique:

BIO *out;\n\nout = BIO_new(BIO_s_file());\nif (out == NULL)\n    /* Error */\nif (BIO_write_filename(out, \"filename.txt\") <= 0)\n    /* Error */\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n
"},{"location":"man3/BIO_s_file/#bugs","title":"BUGS","text":"

BIO_reset() and BIO_seek() are implemented using fseek() on the underlying stream. The return value for fseek() is 0 for success or -1 if an error occurred this differs from other types of BIO which will typically return 1 for success and a non positive value if an error occurred.

"},{"location":"man3/BIO_s_file/#see-also","title":"SEE ALSO","text":"

BIO_seek(3), BIO_tell(3), BIO_reset(3), BIO_flush(3), BIO_read_ex(3), BIO_write_ex(3), BIO_puts(3), BIO_gets(3), BIO_printf(3), BIO_set_close(3), BIO_get_close(3)

"},{"location":"man3/BIO_s_file/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BIO_s_mem/","title":"BIO_s_mem","text":""},{"location":"man3/BIO_s_mem/#name","title":"NAME","text":"

BIO_s_secmem, BIO_s_dgram_mem, BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO

"},{"location":"man3/BIO_s_mem/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_mem(void);\nconst BIO_METHOD *BIO_s_dgram_mem(void);\nconst BIO_METHOD *BIO_s_secmem(void);\n\nBIO_set_mem_eof_return(BIO *b, int v);\nlong BIO_get_mem_data(BIO *b, char **pp);\nBIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);\nBIO_get_mem_ptr(BIO *b, BUF_MEM **pp);\n\nBIO *BIO_new_mem_buf(const void *buf, int len);\n
"},{"location":"man3/BIO_s_mem/#description","title":"DESCRIPTION","text":"

BIO_s_mem() returns the memory BIO method function.

A memory BIO is a source/sink BIO which uses memory for its I/O. Data written to a memory BIO is stored in a BUF_MEM structure which is extended as appropriate to accommodate the stored data.

BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used for buffer storage.

BIO_s_dgram_mem() is a memory BIO that respects datagram semantics. A single call to BIO_write(3) will write a single datagram to the memory BIO. A subsequent call to BIO_read(3) will read the data in that datagram. The BIO_read(3) call will never return more data than was written in the original BIO_write(3) call even if there were subsequent BIO_write(3) calls that wrote more datagrams. Each successive call to BIO_read(3) will read the next datagram. If a BIO_read(3) call supplies a read buffer that is smaller than the size of the datagram, then the read buffer will be completely filled and the remaining data from the datagram will be discarded.

It is not possible to write a zero length datagram. Calling BIO_write(3) in this case will return 0 and no datagrams will be written. Calling BIO_read(3) when there are no datagrams in the BIO to read will return a negative result and the \"retry\" flags will be set (i.e. calling BIO_should_retry(3) will return true). A datagram mem BIO will never return true from BIO_eof(3).

Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read only any data read from it is deleted from the BIO.

Memory BIOs except BIO_s_dgram_mem() support BIO_gets() and BIO_puts().

BIO_s_dgram_mem() supports BIO_sendmmsg(3) and BIO_recvmmsg(3) calls and calls related to BIO_ADDR and MTU handling similarly to the BIO_s_dgram_pair(3).

If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying BUF_MEM structure is also freed.

Calling BIO_reset() on a read write memory BIO clears any data in it if the flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read pointer to the state it was just after the last write was performed and the data can be read again. On a read only BIO it similarly restores the BIO to its original state and the read only data can be read again.

BIO_eof() is true if no data is in the BIO.

BIO_ctrl_pending() returns the number of bytes currently stored.

BIO_set_mem_eof_return() sets the behaviour of memory BIO b when it is empty. If the v is zero then an empty memory BIO will return EOF (that is it will return zero and BIO_should_retry(b) will be false. If v is non zero then it will return v when it is empty and it will set the read retry flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal positive return value v should be set to a negative value, typically -1. Calling this macro will fail for datagram mem BIOs.

BIO_get_mem_data() sets *pp to a pointer to the start of the memory BIOs data and returns the total amount of data available. It is implemented as a macro. Note the pointer returned by this call is informative, no transfer of ownership of this memory is implied. See notes on BIO_set_close().

BIO_set_mem_buf() sets the internal BUF_MEM structure to bm and sets the close flag to c, that is c should be either BIO_CLOSE or BIO_NOCLOSE. It is a macro.

BIO_get_mem_ptr() places the underlying BUF_MEM structure in *pp. It is a macro.

BIO_new_mem_buf() creates a memory BIO using len bytes of data at buf, if len is -1 then the buf is assumed to be nul terminated and its length is determined by strlen. The BIO is set to a read only state and as a result cannot be written to. This is useful when some data needs to be made available from a static area of memory in the form of a BIO. The supplied data is read directly from the supplied buffer: it is not copied first, so the supplied area of memory must be unchanged until the BIO is freed.

All of the five functions described above return an error with BIO_s_dgram_mem().

"},{"location":"man3/BIO_s_mem/#notes","title":"NOTES","text":"

Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely. An exception is BIO_s_dgram_mem() when BIO_set_write_buf_size(3) is called on it. In such case the write buffer size will be fixed and any writes that would overflow the buffer will return an error.

Every write after partial read (not all data in the memory buffer was read) to a read write memory BIO will have to move the unread data with an internal copy operation, if a BIO contains a lot of data and it is read in small chunks intertwined with writes the operation can be very slow. Adding a buffering BIO to the chain can speed up the process.

Calling BIO_set_mem_buf() on a secmem or dgram BIO will give undefined results, including perhaps a program crash.

Switching a memory BIO from read write to read only is not supported and can give undefined results including a program crash. There are two notable exceptions to the rule. The first one is to assign a static memory buffer immediately after BIO creation and set the BIO as read only.

The other supported sequence is to start with a read write BIO then temporarily switch it to read only and call BIO_reset() on the read only BIO immediately before switching it back to read write. Before the BIO is freed it must be switched back to the read write mode.

Calling BIO_get_mem_ptr() on read only BIO will return a BUF_MEM that contains only the remaining data to be read. If the close status of the BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer in it must be set to NULL as the data pointer does not point to an allocated memory.

Calling BIO_reset() on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST flag set can have unexpected outcome when the reads and writes to the BIO are intertwined. As documented above the BIO will be reset to the state after the last completed write operation. The effects of reads preceding that write operation cannot be undone.

Calling BIO_get_mem_ptr() prior to a BIO_reset() call with BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.

Calling BIO_set_close() with BIO_NOCLOSE orphans the BUF_MEM internal to the BIO, _not_ its actual data buffer. See the examples section for the proper method for claiming ownership of the data pointer for a deferred free operation.

"},{"location":"man3/BIO_s_mem/#return-values","title":"RETURN VALUES","text":"

BIO_s_mem(), BIO_s_dgram_mem() and BIO_s_secmem() return a valid memory BIO_METHOD structure.

BIO_set_mem_eof_return(), BIO_set_mem_buf() and BIO_get_mem_ptr() return 1 on success or a value which is less than or equal to 0 if an error occurred.

BIO_get_mem_data() returns the total number of bytes available on success, 0 if b is NULL, or a negative value in case of other errors.

BIO_new_mem_buf() returns a valid BIO structure on success or NULL on error.

"},{"location":"man3/BIO_s_mem/#examples","title":"EXAMPLES","text":"

Create a memory BIO and write some data to it:

BIO *mem = BIO_new(BIO_s_mem());\n\nBIO_puts(mem, \"Hello World\\n\");\n

Create a read only memory BIO:

char data[] = \"Hello World\";\nBIO *mem = BIO_new_mem_buf(data, -1);\n

Extract the BUF_MEM structure from a memory BIO and then free up the BIO:

BUF_MEM *bptr;\n\nBIO_get_mem_ptr(mem, &bptr);\nBIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */\nBIO_free(mem);\n

Extract the BUF_MEM ptr, claim ownership of the internal data and free the BIO and BUF_MEM structure:

BUF_MEM *bptr;\nchar *data;\n\nBIO_get_mem_data(bio, &data);\nBIO_get_mem_ptr(bio, &bptr);\nBIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */\nBIO_free(bio);\nbptr->data = NULL; /* Tell BUF_MEM to orphan data */\nBUF_MEM_free(bptr);\n...\nfree(data);\n
"},{"location":"man3/BIO_s_mem/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/BIO_s_null/","title":"BIO_s_null","text":""},{"location":"man3/BIO_s_null/#name","title":"NAME","text":"

BIO_s_null - null data sink

"},{"location":"man3/BIO_s_null/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_null(void);\n
"},{"location":"man3/BIO_s_null/#description","title":"DESCRIPTION","text":"

BIO_s_null() returns the null sink BIO method. Data written to the null sink is discarded, reads return EOF.

"},{"location":"man3/BIO_s_null/#notes","title":"NOTES","text":"

A null sink BIO behaves in a similar manner to the Unix /dev/null device.

A null bio can be placed on the end of a chain to discard any data passed through it.

A null sink is useful if, for example, an application wishes to digest some data by writing through a digest bio but not send the digested data anywhere. Since a BIO chain must normally include a source/sink BIO this can be achieved by adding a null sink BIO to the end of the chain

"},{"location":"man3/BIO_s_null/#return-values","title":"RETURN VALUES","text":"

BIO_s_null() returns the null sink BIO method.

"},{"location":"man3/BIO_s_null/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/BIO_s_socket/","title":"BIO_s_socket","text":""},{"location":"man3/BIO_s_socket/#name","title":"NAME","text":"

BIO_s_socket, BIO_new_socket - socket BIO

"},{"location":"man3/BIO_s_socket/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_socket(void);\n\nBIO *BIO_new_socket(int sock, int close_flag);\n
"},{"location":"man3/BIO_s_socket/#description","title":"DESCRIPTION","text":"

BIO_s_socket() returns the socket BIO method. This is a wrapper round the platform's socket routines.

BIO_read_ex() and BIO_write_ex() read or write the underlying socket. BIO_puts() is supported but BIO_gets() is not.

If the close flag is set then the socket is shut down and closed when the BIO is freed.

BIO_new_socket() returns a socket BIO using sock and close_flag.

"},{"location":"man3/BIO_s_socket/#notes","title":"NOTES","text":"

Socket BIOs also support any relevant functionality of file descriptor BIOs.

The reason for having separate file descriptor and socket BIOs is that on some platforms sockets are not file descriptors and use distinct I/O routines, Windows is one such platform. Any code mixing the two will not work on all platforms.

"},{"location":"man3/BIO_s_socket/#return-values","title":"RETURN VALUES","text":"

BIO_s_socket() returns the socket BIO method.

BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred.

"},{"location":"man3/BIO_s_socket/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/BIO_sendmmsg/","title":"BIO_sendmmsg","text":""},{"location":"man3/BIO_sendmmsg/#name","title":"NAME","text":"

BIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap, BIO_err_is_non_fatal - send and receive multiple datagrams in a single call

"},{"location":"man3/BIO_sendmmsg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef struct bio_msg_st {\n    void *data;\n    size_t data_len;\n    BIO_ADDR *peer, *local;\n    uint64_t flags;\n} BIO_MSG;\n\nint BIO_sendmmsg(BIO *b, BIO_MSG *msg,\n                 size_t stride, size_t num_msg, uint64_t flags,\n                 size_t *msgs_processed);\nint BIO_recvmmsg(BIO *b, BIO_MSG *msg,\n                 size_t stride, size_t num_msg, uint64_t flags,\n                 size_t *msgs_processed);\n\nint BIO_dgram_set_local_addr_enable(BIO *b, int enable);\nint BIO_dgram_get_local_addr_enable(BIO *b, int *enable);\nint BIO_dgram_get_local_addr_cap(BIO *b);\nint BIO_err_is_non_fatal(unsigned int errcode);\n
"},{"location":"man3/BIO_sendmmsg/#description","title":"DESCRIPTION","text":"

BIO_sendmmsg() and BIO_recvmmsg() functions can be used to send and receive multiple messages in a single call to a BIO. They are analogous to sendmmsg(2) and recvmmsg(2) on operating systems which provide those functions.

The BIO_MSG structure provides a subset of the functionality of the struct msghdr structure defined by POSIX. These functions accept an array of BIO_MSG structures. On any particular invocation, these functions may process all of the passed structures, some of them, or none of them. This is indicated by the value stored in *msgs_processed, which expresses the number of messages processed.

The caller should set the data member of a BIO_MSG to a buffer containing the data to send, or to be filled with a received message. data_len should be set to the size of the buffer in bytes. If the given BIO_MSG is processed (in other words, if the integer returned by the function is greater than or equal to that BIO_MSG's array index), data_len will be modified to specify the actual amount of data sent or received.

The flags field of a BIO_MSG provides input per-message flags to the invocation. If the invocation processes that BIO_MSG, the flags field is written with output per-message flags, or zero if no such flags are applicable.

Currently, no input or output per-message flags are defined and this field should be set to zero before calling BIO_sendmmsg() or BIO_recvmmsg().

The flags argument to BIO_sendmmsg() and BIO_recvmmsg() provides global flags which affect the entire invocation. No global flags are currently defined and this argument should be set to zero.

When these functions are used to send and receive datagrams, the peer field of a BIO_MSG allows the destination address of sent datagrams to be specified on a per-datagram basis, and the source address of received datagrams to be determined. The peer field should be set to point to a BIO_ADDR, which will be read by BIO_sendmmsg() and used as the destination address for sent datagrams, and written by BIO_recvmmsg() with the source address of received datagrams.

Similarly, the local field of a BIO_MSG allows the source address of sent datagrams to be specified on a per-datagram basis, and the destination address of received datagrams to be determined. Unlike peer, support for local must be explicitly enabled on a BIO before it can be used; see BIO_dgram_set_local_addr_enable(). If local is non-NULL in a BIO_MSG and support for local has not been enabled, processing of that BIO_MSG fails.

peer and local should be set to NULL if they are not required. Support for local may not be available on all platforms; on these platforms, these functions always fail if local is non-NULL.

If local is specified and local address support is enabled, but the operating system does not report a local address for a specific received message, the BIO_ADDR it points to will be cleared (address family set to AF_UNSPEC). This is known to happen on Windows when a packet is received which was sent by the local system, regardless of whether the packet's destination address was the loopback address or the IP address of a local non-loopback interface. This is also known to happen on macOS in some circumstances, such as for packets sent before local address support was enabled for a receiving socket. These are OS-specific limitations. As such, users of this API using local address support should expect to sometimes receive a cleared local BIO_ADDR instead of the correct value.

The stride argument must be set to sizeof(BIO_MSG). This argument facilitates backwards compatibility if fields are added to BIO_MSG. Callers must zero-initialize BIO_MSG.

num_msg should be sent to the maximum number of messages to send or receive, which is also the length of the array pointed to by msg.

msgs_processed must be non-NULL and points to an integer written with the number of messages successfully processed; see the RETURN VALUES section for further discussion.

Unlike most BIO functions, these functions explicitly support multi-threaded use. Multiple concurrent writers and multiple concurrent readers of the same BIO are permitted in any combination. As such, these functions do not clear, set, or otherwise modify BIO retry flags. The return value must be used to determine whether an operation should be retried; see below.

The support for concurrent use extends to BIO_sendmmsg() and BIO_recvmmsg() only, and no other function may be called on a given BIO while any call to BIO_sendmmsg() or BIO_recvmmsg() is in progress, or vice versa.

BIO_dgram_set_local_addr_enable() and BIO_dgram_get_local_addr_enable() control whether local address support is enabled. To enable local address support, call BIO_dgram_set_local_addr_enable() with an argument of 1. The call will fail if local address support is not available for the platform. BIO_dgram_get_local_addr_enable() retrieves the value set by BIO_dgram_set_local_addr_enable().

BIO_dgram_get_local_addr_cap() determines if the BIO is capable of supporting local addresses.

BIO_err_is_non_fatal() determines if a packed error code represents an error which is transient in nature.

"},{"location":"man3/BIO_sendmmsg/#notes","title":"NOTES","text":"

Some implementations of the BIO_sendmmsg() and BIO_recvmmsg() BIO methods might always process at most one message at a time, for example when OS-level functionality to transmit or receive multiple messages at a time is not available.

"},{"location":"man3/BIO_sendmmsg/#return-values","title":"RETURN VALUES","text":"

On success, the functions BIO_sendmmsg() and BIO_recvmmsg() return 1 and write the number of messages successfully processed (which need not be nonzero) to msgs_processed. Where a positive value n is written to msgs_processed, all entries in the BIO_MSG array from 0 through n-1 inclusive have their data_len and flags fields updated with the results of the operation on that message. If the call was to BIO_recvmmsg() and the peer or local fields of that message are non-NULL, the BIO_ADDR structures they point to are written with the relevant address.

On failure, the functions BIO_sendmmsg() and BIO_recvmmsg() return 0 and write zero to msgs_processed. Thus msgs_processed is always written regardless of the outcome of the function call.

If BIO_sendmmsg() and BIO_recvmmsg() fail, they always raise an ERR_LIB_BIO error using ERR_raise(3). Any error may be raised, but the following in particular may be noted:

Third parties implementing custom BIOs supporting the BIO_sendmmsg() or BIO_recvmmsg() methods should note that it is a required part of the API contract that an error is always raised when either of these functions return 0.

BIO_dgram_set_local_addr_enable() returns 1 if local address support was successfully enabled or disabled and 0 otherwise.

BIO_dgram_get_local_addr_enable() returns 1 if the local address support enable flag was successfully retrieved.

BIO_dgram_get_local_addr_cap() returns 1 if the BIO can support local addresses.

BIO_err_is_non_fatal() returns 1 if the passed packed error code represents an error which is transient in nature.

"},{"location":"man3/BIO_sendmmsg/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_sendmmsg/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/BIO_set_callback/","title":"BIO_set_callback","text":""},{"location":"man3/BIO_set_callback/#name","title":"NAME","text":"

BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn - BIO callback functions

"},{"location":"man3/BIO_set_callback/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,\n                                   size_t len, int argi,\n                                   long argl, int ret, size_t *processed);\n\nvoid BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);\nBIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);\n\nvoid BIO_set_callback_arg(BIO *b, char *arg);\nchar *BIO_get_callback_arg(const BIO *b);\n\nlong BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,\n                           int argi, long argl, int ret, size_t *processed);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,\n                                long argl, long ret);\nvoid BIO_set_callback(BIO *b, BIO_callback_fn cb);\nBIO_callback_fn BIO_get_callback(const BIO *b);\nlong BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,\n                        long argl, long ret);\n\ntypedef struct bio_mmsg_cb_args_st {\n    BIO_MSG    *msg;\n    size_t      stride, num_msg;\n    uint64_t    flags;\n    size_t     *msgs_processed;\n} BIO_MMSG_CB_ARGS;\n
"},{"location":"man3/BIO_set_callback/#description","title":"DESCRIPTION","text":"

BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO callback. The callback is called during most high-level BIO operations. It can be used for debugging purposes to trace operations on a BIO or to modify its operation.

BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO callback. New code should not use these functions, but they are retained for backwards compatibility. Any callback set via BIO_set_callback_ex() will get called in preference to any set by BIO_set_callback().

BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be used to set and retrieve an argument for use in the callback.

BIO_debug_callback_ex() is a standard debugging callback which prints out information relating to each BIO operation. If the callback argument is set it is interpreted as a BIO to send the information to, otherwise stderr is used. The BIO_debug_callback() function is the deprecated version of the same callback for use with the old callback format BIO_set_callback() function.

BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn is the type of the old format callback function. The meaning of each argument is described below:

The callback should normally simply return ret when it has finished processing, unless it specifically wishes to modify the value returned to the application.

"},{"location":"man3/BIO_set_callback/#callback-operations","title":"CALLBACK OPERATIONS","text":"

In the notes below, callback defers to the actual callback function that is called.

"},{"location":"man3/BIO_set_callback/#return-values","title":"RETURN VALUES","text":"

BIO_get_callback_ex() and BIO_get_callback() return the callback function previously set by a call to BIO_set_callback_ex() and BIO_set_callback() respectively.

BIO_get_callback_arg() returns a char pointer to the value previously set via a call to BIO_set_callback_arg().

BIO_debug_callback() returns 1 or ret if it's called after specific BIO operations.

"},{"location":"man3/BIO_set_callback/#examples","title":"EXAMPLES","text":"

The BIO_debug_callback_ex() function is an example, its source is in crypto/bio/bio_cb.c

"},{"location":"man3/BIO_set_callback/#history","title":"HISTORY","text":"

The BIO_debug_callback_ex() function was added in OpenSSL 3.0.

BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead.

"},{"location":"man3/BIO_set_callback/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BIO_should_retry/","title":"BIO_should_retry","text":""},{"location":"man3/BIO_should_retry/#name","title":"NAME","text":"

BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry functions

"},{"location":"man3/BIO_should_retry/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_should_read(BIO *b);\nint BIO_should_write(BIO *b);\nint BIO_should_io_special(iBIO *b);\nint BIO_retry_type(BIO *b);\nint BIO_should_retry(BIO *b);\n\nBIO *BIO_get_retry_BIO(BIO *bio, int *reason);\nint BIO_get_retry_reason(BIO *bio);\nvoid BIO_set_retry_reason(BIO *bio, int reason);\n
"},{"location":"man3/BIO_should_retry/#description","title":"DESCRIPTION","text":"

These functions determine why a BIO is not able to read or write data. They will typically be called after a failed BIO_read_ex() or BIO_write_ex() call.

BIO_should_retry() is true if the call that produced this condition should then be retried at a later time.

If BIO_should_retry() is false then the cause is an error condition.

BIO_should_read() is true if the cause of the condition is that the BIO has insufficient data to return. Check for readability and/or retry the last operation.

BIO_should_write() is true if the cause of the condition is that the BIO has pending data to write. Check for writability and/or retry the last operation.

BIO_should_io_special() is true if some \"special\" condition, that is a reason other than reading or writing is the cause of the condition.

BIO_retry_type() returns a mask of the cause of a retry condition consisting of the values BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL though current BIO types will only set one of these.

BIO_get_retry_BIO() determines the precise reason for the special condition, it returns the BIO that caused this condition and if reason is not NULL it contains the reason code. The meaning of the reason code and the action that should be taken depends on the type of BIO that resulted in this condition.

BIO_get_retry_reason() returns the reason for a special condition if passed the relevant BIO, for example as returned by BIO_get_retry_BIO().

BIO_set_retry_reason() sets the retry reason for a special condition for a given BIO. This would usually only be called by BIO implementations.

"},{"location":"man3/BIO_should_retry/#notes","title":"NOTES","text":"

BIO_should_read(), BIO_should_write(), BIO_should_io_special(), BIO_retry_type(), and BIO_should_retry(), are implemented as macros.

If BIO_should_retry() returns false then the precise \"error condition\" depends on the BIO type that caused it and the return code of the BIO operation. For example if a call to BIO_read_ex() on a socket BIO returns 0 and BIO_should_retry() is false then the cause will be that the connection closed. A similar condition on a file BIO will mean that it has reached EOF. Some BIO types may place additional information on the error queue. For more details see the individual BIO type manual pages.

If the underlying I/O structure is in a blocking mode almost all current BIO types will not request a retry, because the underlying I/O calls will not. If the application knows that the BIO type will never signal a retry then it need not call BIO_should_retry() after a failed BIO I/O call. This is typically done with file BIOs.

SSL BIOs are the only current exception to this rule: they can request a retry even if the underlying I/O structure is blocking, if a handshake occurs during a call to BIO_read(). An application can retry the failed call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY on the underlying SSL structure.

While an application may retry a failed non blocking call immediately this is likely to be very inefficient because the call will fail repeatedly until data can be processed or is available. An application will normally wait until the necessary condition is satisfied. How this is done depends on the underlying I/O structure.

For example if the cause is ultimately a socket and BIO_should_read() is true then a call to select() may be made to wait until data is available and then retry the BIO operation. By combining the retry conditions of several non blocking BIOs in a single select() call it is possible to service several BIOs in a single thread, though the performance may be poor if SSL BIOs are present because long delays can occur during the initial handshake process.

It is possible for a BIO to block indefinitely if the underlying I/O structure cannot process or return any data. This depends on the behaviour of the platforms I/O functions. This is often not desirable: one solution is to use non blocking I/O and use a timeout on the select() (or equivalent) call.

"},{"location":"man3/BIO_should_retry/#bugs","title":"BUGS","text":"

The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: that is they cannot retry after a partial read or write. This is usually worked around by only passing the relevant data to ASN1 functions when the entire structure can be read or written.

"},{"location":"man3/BIO_should_retry/#return-values","title":"RETURN VALUES","text":"

BIO_should_read(), BIO_should_write(), BIO_should_io_special(), and BIO_should_retry() return either 1 or 0 based on the actual conditions of the BIO.

BIO_retry_type() returns a flag combination presenting the cause of a retry condition or false if there is no retry condition.

BIO_get_retry_BIO() returns a valid BIO structure.

BIO_get_retry_reason() returns the reason for a special condition.

"},{"location":"man3/BIO_should_retry/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_should_retry/#history","title":"HISTORY","text":"

The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_should_retry/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 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.

"},{"location":"man3/BIO_socket_wait/","title":"BIO_socket_wait","text":""},{"location":"man3/BIO_socket_wait/#name","title":"NAME","text":"

BIO_socket_wait, BIO_wait, BIO_do_connect_retry - BIO connection utility functions

"},{"location":"man3/BIO_socket_wait/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\n#ifndef OPENSSL_NO_SOCK\nint BIO_socket_wait(int fd, int for_read, time_t max_time);\n#endif\nint BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds);\nint BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);\n
"},{"location":"man3/BIO_socket_wait/#description","title":"DESCRIPTION","text":"

BIO_socket_wait() waits on the socket fd for reading if for_read is not 0, else for writing, at most until max_time. It succeeds immediately if max_time == 0 (which means no timeout given).

BIO_wait() waits at most until max_time on the given (typically socket-based) bio, for reading if bio is supposed to read, else for writing. It is used by BIO_do_connect_retry() and can be used together BIO_read(3). It succeeds immediately if max_time == 0 (which means no timeout given). If sockets are not available it supports polling by succeeding after sleeping at most the given nap_milliseconds in order to avoid a tight busy loop. Via nap_milliseconds the caller determines the polling granularity.

BIO_do_connect_retry() connects via the given bio. It retries BIO_do_connect() as far as needed to reach a definite outcome, i.e., connection succeeded, timeout has been reached, or an error occurred. For nonblocking and potentially even non-socket BIOs it polls every nap_milliseconds and sleeps in between using BIO_wait(). If nap_milliseconds is < 0 then a default value of 100 ms is used. If the timeout parameter is > 0 this indicates the maximum number of seconds to wait until the connection is established or a definite error occurred. A value of 0 enables waiting indefinitely (i.e, no timeout), while a value < 0 means that BIO_do_connect() is tried only once. The function may, directly or indirectly, invoke ERR_clear_error().

"},{"location":"man3/BIO_socket_wait/#return-values","title":"RETURN VALUES","text":"

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() return -1 on error, 0 on timeout, and 1 on success.

"},{"location":"man3/BIO_socket_wait/#see-also","title":"SEE ALSO","text":"

BIO_do_connect(3), BIO_read(3)

"},{"location":"man3/BIO_socket_wait/#history","title":"HISTORY","text":"

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() were added in OpenSSL 3.0.

"},{"location":"man3/BIO_socket_wait/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BN_BLINDING_new/","title":"BN_BLINDING_new","text":""},{"location":"man3/BN_BLINDING_new/#name","title":"NAME","text":"

BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions

"},{"location":"man3/BN_BLINDING_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,\n                             BIGNUM *mod);\nvoid BN_BLINDING_free(BN_BLINDING *b);\nint BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,\n                           BN_CTX *ctx);\nint BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,\n                          BN_CTX *ctx);\nint BN_BLINDING_is_current_thread(BN_BLINDING *b);\nvoid BN_BLINDING_set_current_thread(BN_BLINDING *b);\nint BN_BLINDING_lock(BN_BLINDING *b);\nint BN_BLINDING_unlock(BN_BLINDING *b);\nunsigned long BN_BLINDING_get_flags(const BN_BLINDING *b);\nvoid BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags);\nBN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,\n                                      const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,\n                                      int (*bn_mod_exp)(BIGNUM *r,\n                                                        const BIGNUM *a,\n                                                        const BIGNUM *p,\n                                                        const BIGNUM *m,\n                                                        BN_CTX *ctx,\n                                                        BN_MONT_CTX *m_ctx),\n                                      BN_MONT_CTX *m_ctx);\n
"},{"location":"man3/BN_BLINDING_new/#description","title":"DESCRIPTION","text":"

BN_BLINDING_new() allocates a new BN_BLINDING structure and copies the A and Ai values into the newly created BN_BLINDING object.

BN_BLINDING_free() frees the BN_BLINDING structure. If b is NULL, nothing is done.

BN_BLINDING_update() updates the BN_BLINDING parameters by squaring the A and Ai or, after specific number of uses and if the necessary parameters are set, by re-creating the blinding parameters.

BN_BLINDING_convert_ex() multiplies n with the blinding factor A. If r is not NULL a copy the inverse blinding factor Ai will be returned in r (this is useful if a RSA object is shared among several threads). BN_BLINDING_invert_ex() multiplies n with the inverse blinding factor Ai. If r is not NULL it will be used as the inverse blinding.

BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with r set to NULL.

BN_BLINDING_is_current_thread() returns whether the BN_BLINDING structure is owned by the current thread. This is to help users provide proper locking if needed for multi-threaded use.

BN_BLINDING_set_current_thread() sets the current thread as the owner of the BN_BLINDING structure.

BN_BLINDING_lock() locks the BN_BLINDING structure.

BN_BLINDING_unlock() unlocks the BN_BLINDING structure.

BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently there are two supported flags: BN_BLINDING_NO_UPDATE and BN_BLINDING_NO_RECREATE. BN_BLINDING_NO_UPDATE inhibits the automatic update of the BN_BLINDING parameters after each use and BN_BLINDING_NO_RECREATE inhibits the automatic re-creation of the BN_BLINDING parameters after a fixed number of uses (currently 32). In newly allocated BN_BLINDING objects no flags are set. BN_BLINDING_set_flags() sets the BN_BLINDING parameters flags.

BN_BLINDING_create_param() creates new BN_BLINDING parameters using the exponent e and the modulus m. bn_mod_exp and m_ctx can be used to pass special functions for exponentiation (normally BN_mod_exp_mont() and BN_MONT_CTX).

"},{"location":"man3/BN_BLINDING_new/#return-values","title":"RETURN VALUES","text":"

BN_BLINDING_new() returns the newly allocated BN_BLINDING structure or NULL in case of an error.

BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on success and 0 if an error occurred.

BN_BLINDING_is_current_thread() returns 1 if the current thread owns the BN_BLINDING object, 0 otherwise.

BN_BLINDING_set_current_thread() doesn't return anything.

BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation succeeded or 0 on error.

BN_BLINDING_get_flags() returns the currently set BN_BLINDING flags (a unsigned long value).

BN_BLINDING_create_param() returns the newly created BN_BLINDING parameters or NULL on error.

"},{"location":"man3/BN_BLINDING_new/#history","title":"HISTORY","text":"

BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().

"},{"location":"man3/BN_BLINDING_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2005-2017 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.

"},{"location":"man3/BN_CTX_new/","title":"BN_CTX_new","text":""},{"location":"man3/BN_CTX_new/#name","title":"NAME","text":"

BN_CTX_new_ex, BN_CTX_new, BN_CTX_secure_new_ex, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures

"},{"location":"man3/BN_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_CTX *BN_CTX_new_ex(OSSL_LIB_CTX *ctx);\nBN_CTX *BN_CTX_new(void);\n\nBN_CTX *BN_CTX_secure_new_ex(OSSL_LIB_CTX *ctx);\nBN_CTX *BN_CTX_secure_new(void);\n\nvoid BN_CTX_free(BN_CTX *c);\n
"},{"location":"man3/BN_CTX_new/#description","title":"DESCRIPTION","text":"

A BN_CTX is a structure that holds BIGNUM temporary variables used by library functions. Since dynamic memory allocation to create BIGNUMs is rather expensive when used in conjunction with repeated subroutine calls, the BN_CTX structure is used.

BN_CTX_new_ex() allocates and initializes a BN_CTX structure for the given library context ctx. The <ctx> value may be NULL in which case the default library context will be used. BN_CTX_new() is the same as BN_CTX_new_ex() except that the default library context is always used.

BN_CTX_secure_new_ex() allocates and initializes a BN_CTX structure but uses the secure heap (see CRYPTO_secure_malloc(3)) to hold the BIGNUMs for the given library context ctx. The <ctx> value may be NULL in which case the default library context will be used. BN_CTX_secure_new() is the same as BN_CTX_secure_new_ex() except that the default library context is always used.

BN_CTX_free() frees the components of the BN_CTX and the structure itself. Since BN_CTX_start() is required in order to obtain BIGNUMs from the BN_CTX, in most cases BN_CTX_end() must be called before the BN_CTX may be freed by BN_CTX_free(). If c is NULL, nothing is done.

A given BN_CTX must only be used by a single thread of execution. No locking is performed, and the internal pool allocator will not properly handle multiple threads of execution.

"},{"location":"man3/BN_CTX_new/#return-values","title":"RETURN VALUES","text":"

BN_CTX_new() and BN_CTX_secure_new() return a pointer to the BN_CTX. If the allocation fails, they return NULL and sets an error code that can be obtained by ERR_get_error(3).

BN_CTX_free() has no return values.

"},{"location":"man3/BN_CTX_new/#removed-functionality","title":"REMOVED FUNCTIONALITY","text":"
void BN_CTX_init(BN_CTX *c);\n

BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should replace use of BN_CTX_init with BN_CTX_new instead:

BN_CTX *ctx;\nctx = BN_CTX_new();\nif (!ctx)\n    /* error */\n...\nBN_CTX_free(ctx);\n
"},{"location":"man3/BN_CTX_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_start(3)

"},{"location":"man3/BN_CTX_new/#history","title":"HISTORY","text":"

BN_CTX_init() was removed in OpenSSL 1.1.0.

"},{"location":"man3/BN_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BN_CTX_start/","title":"BN_CTX_start","text":""},{"location":"man3/BN_CTX_start/#name","title":"NAME","text":"

BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables

"},{"location":"man3/BN_CTX_start/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_CTX_start(BN_CTX *ctx);\n\nBIGNUM *BN_CTX_get(BN_CTX *ctx);\n\nvoid BN_CTX_end(BN_CTX *ctx);\n
"},{"location":"man3/BN_CTX_start/#description","title":"DESCRIPTION","text":"

These functions are used to obtain temporary BIGNUM variables from a BN_CTX (which can been created by using BN_CTX_new(3)) in order to save the overhead of repeatedly creating and freeing BIGNUMs in functions that are called from inside a loop.

A function must call BN_CTX_start() first. Then, BN_CTX_get() may be called repeatedly to obtain temporary BIGNUMs. All BN_CTX_get() calls must be made before calling any other functions that use the ctx as an argument.

Finally, BN_CTX_end() must be called before returning from the function. If ctx is NULL, nothing is done. When BN_CTX_end() is called, the BIGNUM pointers obtained from BN_CTX_get() become invalid.

"},{"location":"man3/BN_CTX_start/#return-values","title":"RETURN VALUES","text":"

BN_CTX_start() and BN_CTX_end() return no values.

BN_CTX_get() returns a pointer to the BIGNUM, or NULL on error. Once BN_CTX_get() has failed, the subsequent calls will return NULL as well, so it is sufficient to check the return value of the last BN_CTX_get() call. In case of an error, an error code is set, which can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_CTX_start/#see-also","title":"SEE ALSO","text":"

BN_CTX_new(3)

"},{"location":"man3/BN_CTX_start/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/BN_add/","title":"BN_add","text":""},{"location":"man3/BN_add/#name","title":"NAME","text":"

BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs

"},{"location":"man3/BN_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);\n\nint BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);\n\nint BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\n\nint BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx);\n\nint BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,\n           BN_CTX *ctx);\n\nint BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nBIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);\n\nint BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);\n\nint BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\n               const BIGNUM *m, BN_CTX *ctx);\n\nint BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/BN_add/#description","title":"DESCRIPTION","text":"

BN_add() adds a and b and places the result in r (r=a+b). r may be the same BIGNUM as a or b.

BN_sub() subtracts b from a and places the result in r (r=a-b). r may be the same BIGNUM as a or b.

BN_mul() multiplies a and b and places the result in r (r=a*b). r may be the same BIGNUM as a or b. For multiplication by powers of 2, use BN_lshift(3).

BN_sqr() takes the square of a and places the result in r (r=a^2). r and a may be the same BIGNUM. This function is faster than BN_mul(r,a,a).

BN_div() divides a by d and places the result in dv and the remainder in rem (dv=a/d, rem=a%d). Either of dv and rem may be NULL, in which case the respective value is not returned. The result is rounded towards zero; thus if a is negative, the remainder will be zero or negative. For division by powers of 2, use BN_rshift(3).

BN_mod() corresponds to BN_div() with dv set to NULL.

BN_nnmod() reduces a modulo m and places the nonnegative remainder in r.

BN_mod_add() adds a to b modulo m and places the nonnegative result in r.

BN_mod_sub() subtracts b from a modulo m and places the nonnegative result in r.

BN_mod_mul() multiplies a by b and finds the nonnegative remainder respective to modulus m (r=(a*b) mod m). r may be the same BIGNUM as a or b. For more efficient algorithms for repeated computations using the same modulus, see BN_mod_mul_montgomery(3) and BN_mod_mul_reciprocal(3).

BN_mod_sqr() takes the square of a modulo m and places the result in r.

BN_mod_sqrt() returns the modular square root of a such that in^2 = a (mod p). The modulus p must be a prime, otherwise an error or an incorrect \"result\" will be returned. The result is stored into in which can be NULL. The result will be newly allocated in that case.

BN_exp() raises a to the p-th power and places the result in r (r=a^p). This function is faster than repeated applications of BN_mul().

BN_mod_exp() computes a to the p-th power modulo m (r=a^p % m). This function uses less time and space than BN_exp(). Do not call this function when m is even and any of the parameters have the BN_FLG_CONSTTIME flag set.

BN_gcd() computes the greatest common divisor of a and b and places the result in r. r may be the same BIGNUM as a or b.

For all functions, ctx is a previously allocated BN_CTX used for temporary variables; see BN_CTX_new(3).

Unless noted otherwise, the result BIGNUM must be different from the arguments.

"},{"location":"man3/BN_add/#notes","title":"NOTES","text":"

For modular operations such as BN_nnmod() or BN_mod_exp() it is an error to use the same BIGNUM object for the modulus as for the output.

"},{"location":"man3/BN_add/#return-values","title":"RETURN VALUES","text":"

The BN_mod_sqrt() returns the result (possibly incorrect if p is not a prime), or NULL.

For all remaining functions, 1 is returned for success, 0 on error. The return value should always be checked (e.g., if (!BN_add(r,a,b)) goto err;). The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_add/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_CTX_new(3), BN_add_word(3), BN_set_bit(3)

"},{"location":"man3/BN_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/BN_add_word/","title":"BN_add_word","text":""},{"location":"man3/BN_add_word/#name","title":"NAME","text":"

BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic functions on BIGNUMs with integers

"},{"location":"man3/BN_add_word/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_add_word(BIGNUM *a, BN_ULONG w);\n\nint BN_sub_word(BIGNUM *a, BN_ULONG w);\n\nint BN_mul_word(BIGNUM *a, BN_ULONG w);\n\nBN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);\n\nBN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);\n
"},{"location":"man3/BN_add_word/#description","title":"DESCRIPTION","text":"

These functions perform arithmetic operations on BIGNUMs with unsigned integers. They are much more efficient than the normal BIGNUM arithmetic operations.

BN_add_word() adds w to a (a+=w).

BN_sub_word() subtracts w from a (a-=w).

BN_mul_word() multiplies a and w (a*=w).

BN_div_word() divides a by w (a/=w) and returns the remainder.

BN_mod_word() returns the remainder of a divided by w (a%w).

For BN_div_word() and BN_mod_word(), w must not be 0.

"},{"location":"man3/BN_add_word/#return-values","title":"RETURN VALUES","text":"

BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

BN_mod_word() and BN_div_word() return a%w on success and (BN_ULONG)-1 if an error occurred.

"},{"location":"man3/BN_add_word/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3)

"},{"location":"man3/BN_add_word/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_bn2bin/","title":"BN_bn2bin","text":""},{"location":"man3/BN_bn2bin/#name","title":"NAME","text":"

BN_bn2binpad, BN_signed_bn2bin, BN_bn2bin, BN_bin2bn, BN_signed_bin2bn, BN_bn2lebinpad, BN_signed_bn2lebin, BN_lebin2bn, BN_signed_lebin2bn, BN_bn2nativepad, BN_signed_bn2native, BN_native2bn, BN_signed_native2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions

"},{"location":"man3/BN_bn2bin/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_bn2bin(const BIGNUM *a, unsigned char *to);\nint BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2bin(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_bin2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nint BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2lebin(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nint BN_bn2nativepad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2native(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_native2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_native2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nchar *BN_bn2hex(const BIGNUM *a);\nchar *BN_bn2dec(const BIGNUM *a);\nint BN_hex2bn(BIGNUM **a, const char *str);\nint BN_dec2bn(BIGNUM **a, const char *str);\n\nint BN_print(BIO *fp, const BIGNUM *a);\nint BN_print_fp(FILE *fp, const BIGNUM *a);\n\nint BN_bn2mpi(const BIGNUM *a, unsigned char *to);\nBIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);\n
"},{"location":"man3/BN_bn2bin/#description","title":"DESCRIPTION","text":"

BN_bn2bin() converts the absolute value of a into big-endian form and stores it at to. to must point to BN_num_bytes(a) bytes of memory. a and to MUST NOT be NULL.

BN_bn2binpad() also converts the absolute value of a into big-endian form and stores it at to. tolen indicates the length of the output buffer to. The result is padded with zeros if necessary. If tolen is less than BN_num_bytes(a) an error is returned.

BN_signed_bn2bin() converts the value of a into big-endian signed 2's complements form and stores it at to. tolen indicates the length of the output buffer to. The result is signed extended (padded with 0x00 for positive numbers or with 0xff for negative numbers) if necessary. If tolen is smaller than the necessary size (which may be <BN_num_bytes(**a**) + 1>), an error is returned.

BN_bin2bn() converts the positive integer in big-endian form of length len at s into a BIGNUM and places it in ret. If ret is NULL, a new BIGNUM is created. s MUST NOT be NULL.

BN_signed_bin2bn() converts the integer in big-endian signed 2's complement form of length len at s into a BIGNUM and places it in ret. If ret is NULL, a new BIGNUM is created.

BN_bn2lebinpad(), BN_signed_bn2lebin() and BN_lebin2bn() are identical to BN_bn2binpad(), BN_signed_bn2bin() and BN_bin2bn() except the buffer is in little-endian format.

BN_bn2nativepad(), BN_signed_bn2native() and BN_native2bn() are identical to BN_bn2binpad(), BN_signed_bn2bin() and BN_bin2bn() except the buffer is in native format, i.e. most significant byte first on big-endian platforms, and least significant byte first on little-endian platforms.

BN_bn2hex() and BN_bn2dec() return printable strings containing the hexadecimal and decimal encoding of a respectively. For negative numbers, the string is prefaced with a leading '-'. The string must be freed later using OPENSSL_free().

BN_hex2bn() takes as many characters as possible from the string str, including the leading character '-' which means negative, to form a valid hexadecimal number representation and converts them to a BIGNUM and stores it in **a. If *a is NULL, a new BIGNUM is created. If a is NULL, it only computes the length of valid representation. A \"negative zero\" is converted to zero. BN_dec2bn() is the same using the decimal system.

BN_print() and BN_print_fp() write the hexadecimal encoding of a, with a leading '-' for negative numbers, to the BIO or FILE fp.

BN_bn2mpi() and BN_mpi2bn() convert BIGNUMs from and to a format that consists of the number's length in bytes represented as a 4-byte big-endian number, and the number itself in big-endian format, where the most significant bit signals a negative number (the representation of numbers with the MSB set is prefixed with null byte).

BN_bn2mpi() stores the representation of a at to, where to must be large enough to hold the result. The size can be determined by calling BN_bn2mpi(a, NULL).

BN_mpi2bn() converts the len bytes long representation at s to a BIGNUM and stores it at ret, or in a newly allocated BIGNUM if ret is NULL.

"},{"location":"man3/BN_bn2bin/#return-values","title":"RETURN VALUES","text":"

BN_bn2bin() returns the length of the big-endian number placed at to. BN_bin2bn() returns the BIGNUM, NULL on error.

BN_bn2binpad(), BN_signed_bn2bin(), BN_bn2lebinpad(), BN_signed_bn2lebin(), BN_bn2nativepad(), and_signed BN_bn2native() return the number of bytes written or -1 if the supplied buffer is too small.

BN_bn2hex() and BN_bn2dec() return a NUL-terminated string, or NULL on error. BN_hex2bn() and BN_dec2bn() return the number of characters used in parsing, or 0 on error, in which case no new BIGNUM will be created.

BN_print_fp() and BN_print() return 1 on success, 0 on write errors.

BN_bn2mpi() returns the length of the representation. BN_mpi2bn() returns the BIGNUM, and NULL on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_bn2bin/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_zero(3), ASN1_INTEGER_to_BN(3), BN_num_bytes(3)

"},{"location":"man3/BN_bn2bin/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/BN_cmp/","title":"BN_cmp","text":""},{"location":"man3/BN_cmp/#name","title":"NAME","text":"

BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_abs_is_word, BN_is_odd, BN_are_coprime - BIGNUM comparison and test functions

"},{"location":"man3/BN_cmp/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_cmp(const BIGNUM *a, const BIGNUM *b);\nint BN_ucmp(const BIGNUM *a, const BIGNUM *b);\n\nint BN_is_zero(const BIGNUM *a);\nint BN_is_one(const BIGNUM *a);\nint BN_is_word(const BIGNUM *a, const BN_ULONG w);\nint BN_abs_is_word(const BIGNUM *a, const BN_ULONG w);\nint BN_is_odd(const BIGNUM *a);\n\nint BN_are_coprime(BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/BN_cmp/#description","title":"DESCRIPTION","text":"

BN_cmp() compares the numbers a and b. BN_ucmp() compares their absolute values.

BN_is_zero(), BN_is_one(), BN_is_word() and BN_abs_is_word() test if a equals 0, 1, w, or |w| respectively. BN_is_odd() tests if a is odd.

BN_are_coprime() determines if a and b are coprime. ctx is used internally for storing temporary variables. The values of a and b and ctx must not be NULL.

"},{"location":"man3/BN_cmp/#return-values","title":"RETURN VALUES","text":"

BN_cmp() returns -1 if a < b, 0 if a == b and 1 if a > b. BN_ucmp() is the same using the absolute values of a and b.

BN_is_zero(), BN_is_one() BN_is_word(), BN_abs_is_word() and BN_is_odd() return 1 if the condition is true, 0 otherwise.

BN_are_coprime() returns 1 if the BIGNUM's are coprime, otherwise it returns 0.

"},{"location":"man3/BN_cmp/#history","title":"HISTORY","text":"

Prior to OpenSSL 1.1.0, BN_is_zero(), BN_is_one(), BN_is_word(), BN_abs_is_word() and BN_is_odd() were macros.

The function BN_are_coprime() was added in OpenSSL 3.1.

"},{"location":"man3/BN_cmp/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BN_copy/","title":"BN_copy","text":""},{"location":"man3/BN_copy/#name","title":"NAME","text":"

BN_copy, BN_dup, BN_with_flags - copy BIGNUMs

"},{"location":"man3/BN_copy/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);\n\nBIGNUM *BN_dup(const BIGNUM *from);\n\nvoid BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);\n
"},{"location":"man3/BN_copy/#description","title":"DESCRIPTION","text":"

BN_copy() copies from to to. BN_dup() creates a new BIGNUM containing the value from.

BN_with_flags creates a temporary shallow copy of b in dest. It places significant restrictions on the copied data. Applications that do no adhere to these restrictions may encounter unexpected side effects or crashes. For that reason use of this function is discouraged. Any flags provided in flags will be set in dest in addition to any flags already set in b. For example this might commonly be used to create a temporary copy of a BIGNUM with the BN_FLG_CONSTTIME flag set for constant time operations. The temporary copy in dest will share some internal state with b. For this reason the following restrictions apply to the use of dest:

"},{"location":"man3/BN_copy/#return-values","title":"RETURN VALUES","text":"

BN_copy() returns to on success, NULL on error. BN_dup() returns the new BIGNUM, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_copy/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/BN_copy/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_generate_prime/","title":"BN_generate_prime","text":""},{"location":"man3/BN_generate_prime/#name","title":"NAME","text":"

BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime, BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality

"},{"location":"man3/BN_generate_prime/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,\n                          const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,\n                          BN_CTX *ctx);\n\nint BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,\n                         const BIGNUM *rem, BN_GENCB *cb);\n\nint BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);\n\nint BN_GENCB_call(BN_GENCB *cb, int a, int b);\n\nBN_GENCB *BN_GENCB_new(void);\n\nvoid BN_GENCB_free(BN_GENCB *cb);\n\nvoid BN_GENCB_set_old(BN_GENCB *gencb,\n                      void (*callback)(int, int, void *), void *cb_arg);\n\nvoid BN_GENCB_set(BN_GENCB *gencb,\n                  int (*callback)(int, int, BN_GENCB *), void *cb_arg);\n\nvoid *BN_GENCB_get_arg(BN_GENCB *cb);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,\n                          BIGNUM *rem, void (*callback)(int, int, void *),\n                          void *cb_arg);\n\nint BN_is_prime(const BIGNUM *p, int nchecks,\n                void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);\n\nint BN_is_prime_fasttest(const BIGNUM *p, int nchecks,\n                         void (*callback)(int, int, void *), BN_CTX *ctx,\n                         void *cb_arg, int do_trial_division);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);\n\nint BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,\n                            int do_trial_division, BN_GENCB *cb);\n
"},{"location":"man3/BN_generate_prime/#description","title":"DESCRIPTION","text":"

BN_generate_prime_ex2() generates a pseudo-random prime number of at least bit length bits using the BN_CTX provided in ctx. The value of ctx must not be NULL.

The returned number is probably prime with a negligible error. The maximum error rate is 2^-128. It's 2^-287 for a 512 bit prime, 2^-435 for a 1024 bit prime, 2^-648 for a 2048 bit prime, and lower than 2^-882 for primes larger than 2048 bit.

If add is NULL the returned prime number will have exact bit length bits with the top most two bits set.

If ret is not NULL, it will be used to store the number.

If cb is not NULL, it is used as follows:

The prime may have to fulfill additional requirements for use in Diffie-Hellman key exchange:

If add is not NULL, the prime will fulfill the condition p % add == rem (p % add == 1 if rem == NULL) in order to suit a given generator.

If safe is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 is also prime). If safe is true, and rem == NULL the condition will be p % add == 3. It is recommended that add is a multiple of 4.

The random generator must be seeded prior to calling BN_generate_prime_ex(). If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail. The random number generator configured for the OSSL_LIB_CTX associated with ctx will be used.

BN_generate_prime_ex() is the same as BN_generate_prime_ex2() except that no ctx parameter is passed. In this case the random number generator associated with the default OSSL_LIB_CTX will be used.

BN_check_prime(), BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and BN_is_prime_fasttest() test if the number p is prime. The functions tests until one of the tests shows that p is composite, or all the tests passed. If p passes all these tests, it is considered a probable prime.

The test performed on p are trial division by a number of small primes and rounds of the of the Miller-Rabin probabilistic primality test.

The functions do at least 64 rounds of the Miller-Rabin test giving a maximum false positive rate of 2^-128. If the size of p is more than 2048 bits, they do at least 128 rounds giving a maximum false positive rate of 2^-256.

If nchecks is larger than the minimum above (64 or 128), nchecks rounds of the Miller-Rabin test will be done.

If do_trial_division set to 0, the trial division will be skipped. BN_is_prime_ex() and BN_is_prime() always skip the trial division.

BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and BN_is_prime_fasttest() are deprecated.

BN_is_prime_fasttest() and BN_is_prime() behave just like BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old style call back.

ctx is a preallocated BN_CTX (to save the overhead of allocating and freeing the structure in a loop), or NULL.

If the trial division is done, and no divisors are found and cb is not NULL, BN_GENCB_call(cb, 1, -1) is called.

After each round of the Miller-Rabin probabilistic primality test, if cb is not NULL, BN_GENCB_call(cb, 1, j) is called with j the iteration (j = 0, 1, ...).

BN_GENCB_call() calls the callback function held in the BN_GENCB structure and passes the ints a and b as arguments. There are two types of BN_GENCB structure that are supported: \"new\" style and \"old\" style. New programs should prefer the \"new\" style, whilst the \"old\" style is provided for backwards compatibility purposes.

A BN_GENCB structure should be created through a call to BN_GENCB_new(), and freed through a call to BN_GENCB_free(). If the argument is NULL, nothing is done.

For \"new\" style callbacks a BN_GENCB structure should be initialised with a call to BN_GENCB_set(), where gencb is a BN_GENCB *, callback is of type int (*callback)(int, int, BN_GENCB *) and cb_arg is a void *. \"Old\" style callbacks are the same except they are initialised with a call to BN_GENCB_set_old() and callback is of type void (*callback)(int, int, void *).

A callback is invoked through a call to BN_GENCB_call. This will check the type of the callback and will invoke callback(a, b, gencb) for new style callbacks or callback(a, b, cb_arg) for old style.

It is possible to obtain the argument associated with a BN_GENCB structure (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.

BN_generate_prime() (deprecated) works in the same way as BN_generate_prime_ex() but expects an old-style callback function directly in the callback parameter, and an argument to pass to it in the cb_arg. BN_is_prime() and BN_is_prime_fasttest() can similarly be compared to BN_is_prime_ex() and BN_is_prime_fasttest_ex(), respectively.

"},{"location":"man3/BN_generate_prime/#return-values","title":"RETURN VALUES","text":"

BN_generate_prime_ex() return 1 on success or 0 on error.

BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime(), BN_is_prime_fasttest() and BN_check_prime return 0 if the number is composite, 1 if it is prime with an error probability of less than 0.25^nchecks, and -1 on error.

BN_generate_prime() returns the prime number on success, NULL otherwise.

BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or NULL otherwise.

BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB structure.

Callback functions should return 1 on success or 0 on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_generate_prime/#removed-functionality","title":"REMOVED FUNCTIONALITY","text":"

As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure directly, as in:

BN_GENCB callback;\n

Instead applications should create a BN_GENCB structure using BN_GENCB_new:

BN_GENCB *callback;\ncallback = BN_GENCB_new();\nif (!callback)\n    /* error */\n...\nBN_GENCB_free(callback);\n
"},{"location":"man3/BN_generate_prime/#see-also","title":"SEE ALSO","text":"

DH_generate_parameters(3), DSA_generate_parameters(3), RSA_generate_key(3), ERR_get_error(3), RAND_bytes(3), RAND(7)

"},{"location":"man3/BN_generate_prime/#history","title":"HISTORY","text":"

The BN_is_prime_ex() and BN_is_prime_fasttest_ex() functions were deprecated in OpenSSL 3.0.

The BN_GENCB_new(), BN_GENCB_free(), and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0.

BN_check_prime() was added in OpenSSL 3.0.

"},{"location":"man3/BN_generate_prime/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/BN_mod_exp_mont/","title":"BN_mod_exp_mont","text":""},{"location":"man3/BN_mod_exp_mont/#name","title":"NAME","text":"

BN_mod_exp_mont, BN_mod_exp_mont_consttime, BN_mod_exp_mont_consttime_x2 - Montgomery exponentiation

"},{"location":"man3/BN_mod_exp_mont/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_mod_exp_mont(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,\n                    const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);\n\nint BN_mod_exp_mont_consttime(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,\n                              const BIGNUM *m, BN_CTX *ctx,\n                              BN_MONT_CTX *in_mont);\n\nint BN_mod_exp_mont_consttime_x2(BIGNUM *rr1, const BIGNUM *a1,\n                                 const BIGNUM *p1, const BIGNUM *m1,\n                                 BN_MONT_CTX *in_mont1, BIGNUM *rr2,\n                                 const BIGNUM *a2, const BIGNUM *p2,\n                                 const BIGNUM *m2, BN_MONT_CTX *in_mont2,\n                                 BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_exp_mont/#description","title":"DESCRIPTION","text":"

BN_mod_exp_mont() computes a to the p-th power modulo m (rr=a^p % m) using Montgomery multiplication. in_mont is a Montgomery context and can be NULL. In the case in_mont is NULL, it will be initialized within the function, so you can save time on initialization if you provide it in advance.

BN_mod_exp_mont_consttime() computes a to the p-th power modulo m (rr=a^p % m) using Montgomery multiplication. It is a variant of BN_mod_exp_mont(3) that uses fixed windows and the special precomputation memory layout to limit data-dependency to a minimum to protect secret exponents. It is called automatically when BN_mod_exp_mont(3) is called with parameters a, p, m, any of which have BN_FLG_CONSTTIME flag.

BN_mod_exp_mont_consttime_x2() computes two independent exponentiations a1 to the p1-th power modulo m1 (rr1=a1^p1 % m1) and a2 to the p2-th power modulo m2 (rr2=a2^p2 % m2) using Montgomery multiplication. For some fixed and equal modulus sizes m1 and m2 it uses optimizations that allow to speedup two exponentiations. In all other cases the function reduces to two calls of BN_mod_exp_mont_consttime(3).

"},{"location":"man3/BN_mod_exp_mont/#return-values","title":"RETURN VALUES","text":"

For all functions 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_exp_mont/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_mod_exp_mont(3)

"},{"location":"man3/BN_mod_exp_mont/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/BN_mod_inverse/","title":"BN_mod_inverse","text":""},{"location":"man3/BN_mod_inverse/#name","title":"NAME","text":"

BN_mod_inverse - compute inverse modulo n

"},{"location":"man3/BN_mod_inverse/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,\n                       BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_inverse/#description","title":"DESCRIPTION","text":"

BN_mod_inverse() computes the inverse of a modulo n places the result in r ((a*r)%n==1). If r is NULL, a new BIGNUM is created.

ctx is a previously allocated BN_CTX used for temporary variables. r may be the same BIGNUM as a.

"},{"location":"man3/BN_mod_inverse/#notes","title":"NOTES","text":"

It is an error to use the same BIGNUM as n.

"},{"location":"man3/BN_mod_inverse/#return-values","title":"RETURN VALUES","text":"

BN_mod_inverse() returns the BIGNUM containing the inverse, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_inverse/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3)

"},{"location":"man3/BN_mod_inverse/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_mod_mul_montgomery/","title":"BN_mod_mul_montgomery","text":""},{"location":"man3/BN_mod_mul_montgomery/#name","title":"NAME","text":"

BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, BN_from_montgomery, BN_to_montgomery - Montgomery multiplication

"},{"location":"man3/BN_mod_mul_montgomery/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_MONT_CTX *BN_MONT_CTX_new(void);\nvoid BN_MONT_CTX_free(BN_MONT_CTX *mont);\n\nint BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);\nBN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);\n\nint BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,\n                          BN_MONT_CTX *mont, BN_CTX *ctx);\n\nint BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,\n                       BN_CTX *ctx);\n\nint BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,\n                     BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_mul_montgomery/#description","title":"DESCRIPTION","text":"

These functions implement Montgomery multiplication. They are used automatically when BN_mod_exp(3) is called with suitable input, but they may be useful when several operations are to be performed using the same modulus.

BN_MONT_CTX_new() allocates and initializes a BN_MONT_CTX structure.

BN_MONT_CTX_set() sets up the mont structure from the modulus m by precomputing its inverse and a value R.

BN_MONT_CTX_copy() copies the BN_MONT_CTX from to to.

BN_MONT_CTX_free() frees the components of the BN_MONT_CTX, and, if it was created by BN_MONT_CTX_new(), also the structure itself. If mont is NULL, nothing is done.

BN_mod_mul_montgomery() computes Mont(a,b):=a*b*R^-1 and places the result in r.

BN_from_montgomery() performs the Montgomery reduction r = a*R^-1.

BN_to_montgomery() computes Mont(a,R^2), i.e. a*R. Note that a must be nonnegative and smaller than the modulus.

For all functions, ctx is a previously allocated BN_CTX used for temporary variables.

"},{"location":"man3/BN_mod_mul_montgomery/#return-values","title":"RETURN VALUES","text":"

BN_MONT_CTX_new() returns the newly allocated BN_MONT_CTX, and NULL on error.

BN_MONT_CTX_free() has no return value.

For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_mul_montgomery/#warnings","title":"WARNINGS","text":"

The inputs must be reduced modulo m, otherwise the result will be outside the expected range.

"},{"location":"man3/BN_mod_mul_montgomery/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_new(3)

"},{"location":"man3/BN_mod_mul_montgomery/#history","title":"HISTORY","text":"

BN_MONT_CTX_init() was removed in OpenSSL 1.1.0

"},{"location":"man3/BN_mod_mul_montgomery/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/BN_mod_mul_reciprocal/","title":"BN_mod_mul_reciprocal","text":""},{"location":"man3/BN_mod_mul_reciprocal/#name","title":"NAME","text":"

BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using reciprocal

"},{"location":"man3/BN_mod_mul_reciprocal/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_RECP_CTX *BN_RECP_CTX_new(void);\nvoid BN_RECP_CTX_free(BN_RECP_CTX *recp);\n\nint BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_div_recp(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, BN_RECP_CTX *recp,\n                BN_CTX *ctx);\n\nint BN_mod_mul_reciprocal(BIGNUM *r, const BIGNUM *a, const BIGNUM *b,\n                          BN_RECP_CTX *recp, BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_mul_reciprocal/#description","title":"DESCRIPTION","text":"

BN_mod_mul_reciprocal() can be used to perform an efficient BN_mod_mul(3) operation when the operation will be performed repeatedly with the same modulus. It computes r=(a*b)%m using recp=1/m, which is set as described below. ctx is a previously allocated BN_CTX used for temporary variables.

BN_RECP_CTX_new() allocates and initializes a BN_RECP structure.

BN_RECP_CTX_free() frees the components of the BN_RECP, and, if it was created by BN_RECP_CTX_new(), also the structure itself. If recp is NULL, nothing is done.

BN_RECP_CTX_set() stores m in recp and sets it up for computing 1/m and shifting it left by BN_num_bits(m)+1 to make it an integer. The result and the number of bits it was shifted left will later be stored in recp.

BN_div_recp() divides a by m using recp. It places the quotient in dv and the remainder in rem.

The BN_RECP_CTX structure cannot be shared between threads.

"},{"location":"man3/BN_mod_mul_reciprocal/#return-values","title":"RETURN VALUES","text":"

BN_RECP_CTX_new() returns the newly allocated BN_RECP_CTX, and NULL on error.

BN_RECP_CTX_free() has no return value.

For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_mul_reciprocal/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_new(3)

"},{"location":"man3/BN_mod_mul_reciprocal/#history","title":"HISTORY","text":"

BN_RECP_CTX_init() was removed in OpenSSL 1.1.0

"},{"location":"man3/BN_mod_mul_reciprocal/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_new/","title":"BN_new","text":""},{"location":"man3/BN_new/#name","title":"NAME","text":"

BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs

"},{"location":"man3/BN_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_new(void);\n\nBIGNUM *BN_secure_new(void);\n\nvoid BN_clear(BIGNUM *a);\n\nvoid BN_free(BIGNUM *a);\n\nvoid BN_clear_free(BIGNUM *a);\n
"},{"location":"man3/BN_new/#description","title":"DESCRIPTION","text":"

BN_new() allocates and initializes a BIGNUM structure. BN_secure_new() does the same except that the secure heap OPENSSL_secure_malloc(3) is used to store the value.

BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the memory used by a and sets it to the value 0. If a is NULL, nothing is done.

BN_free() frees the components of the BIGNUM, and if it was created by BN_new(), also the structure itself. BN_clear_free() additionally overwrites the data before the memory is returned to the system. If a is NULL, nothing is done.

"},{"location":"man3/BN_new/#return-values","title":"RETURN VALUES","text":"

BN_new() and BN_secure_new() return a pointer to the BIGNUM initialised to the value 0. If the allocation fails, they return NULL and set an error code that can be obtained by ERR_get_error(3).

BN_clear(), BN_free() and BN_clear_free() have no return values.

"},{"location":"man3/BN_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), OPENSSL_secure_malloc(3)

"},{"location":"man3/BN_new/#history","title":"HISTORY","text":"

BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.

"},{"location":"man3/BN_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_num_bytes/","title":"BN_num_bytes","text":""},{"location":"man3/BN_num_bytes/#name","title":"NAME","text":"

BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size

"},{"location":"man3/BN_num_bytes/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_num_bytes(const BIGNUM *a);\n\nint BN_num_bits(const BIGNUM *a);\n\nint BN_num_bits_word(BN_ULONG w);\n
"},{"location":"man3/BN_num_bytes/#description","title":"DESCRIPTION","text":"

BN_num_bytes() returns the size of a BIGNUM in bytes.

BN_num_bits_word() returns the number of significant bits in a word. If we take 0x00000432 as an example, it returns 11, not 16, not 32. Basically, except for a zero, it returns floor(log2(w))+1.

BN_num_bits() returns the number of significant bits in a BIGNUM, following the same principle as BN_num_bits_word().

BN_num_bytes() is a macro.

"},{"location":"man3/BN_num_bytes/#return-values","title":"RETURN VALUES","text":"

The size.

"},{"location":"man3/BN_num_bytes/#notes","title":"NOTES","text":"

Some have tried using BN_num_bits() on individual numbers in RSA keys, DH keys and DSA keys, and found that they don't always come up with the number of bits they expected (something like 512, 1024, 2048, ...). This is because generating a number with some specific number of bits doesn't always set the highest bits, thereby making the number of significant bits a little lower. If you want to know the \"key size\" of such a key, either use functions like RSA_size(), DH_size() and DSA_size(), or use BN_num_bytes() and multiply with 8 (although there's no real guarantee that will match the \"key size\", just a lot more probability).

"},{"location":"man3/BN_num_bytes/#see-also","title":"SEE ALSO","text":"

DH_size(3), DSA_size(3), RSA_size(3)

"},{"location":"man3/BN_num_bytes/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/BN_rand/","title":"BN_rand","text":""},{"location":"man3/BN_rand/#name","title":"NAME","text":"

BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand, BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range, BN_pseudo_rand_range - generate pseudo-random number

"},{"location":"man3/BN_rand/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,\n               unsigned int strength, BN_CTX *ctx);\nint BN_rand(BIGNUM *rnd, int bits, int top, int bottom);\n\nint BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,\n                    unsigned int strength, BN_CTX *ctx);\nint BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);\n\nint BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,\n                     BN_CTX *ctx);\nint BN_rand_range(BIGNUM *rnd, const BIGNUM *range);\n\nint BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,\n                          BN_CTX *ctx);\nint BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);\nint BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range);\n
"},{"location":"man3/BN_rand/#description","title":"DESCRIPTION","text":"

BN_rand_ex() generates a cryptographically strong pseudo-random number of bits in length and security strength at least strength bits using the random number generator for the library context associated with ctx. The function stores the generated data in rnd. The parameter ctx may be NULL in which case the default library context is used. If bits is less than zero, or too small to accommodate the requirements specified by the top and bottom parameters, an error is returned. The top parameters specifies requirements on the most significant bit of the generated number. If it is BN_RAND_TOP_ANY, there is no constraint. If it is BN_RAND_TOP_ONE, the top bit must be one. If it is BN_RAND_TOP_TWO, the two most significant bits of the number will be set to 1, so that the product of two such random numbers will always have 2*bits length. If bottom is BN_RAND_BOTTOM_ODD, the number will be odd; if it is BN_RAND_BOTTOM_ANY it can be odd or even. If bits is 1 then top cannot also be BN_RAND_TOP_TWO.

BN_rand() is the same as BN_rand_ex() except that the default library context is always used.

BN_rand_range_ex() generates a cryptographically strong pseudo-random number rnd, of security strength at least strength bits, in the range 0 <= rnd < range using the random number generator for the library context associated with ctx. The parameter ctx may be NULL in which case the default library context is used.

BN_rand_range() is the same as BN_rand_range_ex() except that the default library context is always used.

BN_priv_rand_ex(), BN_priv_rand(), BN_priv_rand_rand_ex() and BN_priv_rand_range() have the same semantics as BN_rand_ex(), BN_rand(), BN_rand_range_ex() and BN_rand_range() respectively. They are intended to be used for generating values that should remain private, and mirror the same difference between RAND_bytes(3) and RAND_priv_bytes(3).

"},{"location":"man3/BN_rand/#notes","title":"NOTES","text":"

Always check the error return value of these functions and do not take randomness for granted: an error occurs if the CSPRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence.

"},{"location":"man3/BN_rand/#return-values","title":"RETURN VALUES","text":"

The functions return 1 on success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_rand/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), RAND_add(3), RAND_bytes(3), RAND_priv_bytes(3), RAND(7), EVP_RAND(7)

"},{"location":"man3/BN_rand/#history","title":"HISTORY","text":""},{"location":"man3/BN_rand/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/BN_security_bits/","title":"BN_security_bits","text":""},{"location":"man3/BN_security_bits/#name","title":"NAME","text":"

BN_security_bits - returns bits of security based on given numbers

"},{"location":"man3/BN_security_bits/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_security_bits(int L, int N);\n
"},{"location":"man3/BN_security_bits/#description","title":"DESCRIPTION","text":"

BN_security_bits() returns the number of bits of security provided by a specific algorithm and a particular key size. The bits of security is defined in NIST SP800-57. Currently, BN_security_bits() support two types of asymmetric algorithms: the FFC (Finite Field Cryptography) and IFC (Integer Factorization Cryptography). For FFC, e.g., DSA and DH, both parameters L and N are used to decide the bits of security, where L is the size of the public key and N is the size of the private key. For IFC, e.g., RSA, only L is used and it's commonly considered to be the key size (modulus).

"},{"location":"man3/BN_security_bits/#return-values","title":"RETURN VALUES","text":"

Number of security bits.

"},{"location":"man3/BN_security_bits/#notes","title":"NOTES","text":"

ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits() function. The symmetric algorithms are not covered neither.

"},{"location":"man3/BN_security_bits/#see-also","title":"SEE ALSO","text":"

DH_security_bits(3), DSA_security_bits(3), RSA_security_bits(3)

"},{"location":"man3/BN_security_bits/#history","title":"HISTORY","text":"

The BN_security_bits() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BN_security_bits/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/BN_set_bit/","title":"BN_set_bit","text":""},{"location":"man3/BN_set_bit/#name","title":"NAME","text":"

BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs

"},{"location":"man3/BN_set_bit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_set_bit(BIGNUM *a, int n);\nint BN_clear_bit(BIGNUM *a, int n);\n\nint BN_is_bit_set(const BIGNUM *a, int n);\n\nint BN_mask_bits(BIGNUM *a, int n);\n\nint BN_lshift(BIGNUM *r, const BIGNUM *a, int n);\nint BN_lshift1(BIGNUM *r, BIGNUM *a);\n\nint BN_rshift(BIGNUM *r, BIGNUM *a, int n);\nint BN_rshift1(BIGNUM *r, BIGNUM *a);\n
"},{"location":"man3/BN_set_bit/#description","title":"DESCRIPTION","text":"

BN_set_bit() sets bit n in a to 1 (a|=(1<<n)). The number is expanded if necessary.

BN_clear_bit() sets bit n in a to 0 (a&=~(1<<n)). An error occurs if a is shorter than n bits.

BN_is_bit_set() tests if bit n in a is set.

BN_mask_bits() truncates a to an n bit number (a&=~((~0)<<n)). An error occurs if n is negative. An error is also returned if the internal representation of a is already shorter than n bits. The internal representation depends on the platform's word size, and this error can be safely ignored. Use BN_num_bits(3) to determine the exact number of bits if needed.

BN_lshift() shifts a left by n bits and places the result in r (r=a*2^n). Note that n must be nonnegative. BN_lshift1() shifts a left by one and places the result in r (r=2*a).

BN_rshift() shifts a right by n bits and places the result in r (r=a/2^n). Note that n must be nonnegative. BN_rshift1() shifts a right by one and places the result in r (r=a/2).

For the shift functions, r and a may be the same variable.

"},{"location":"man3/BN_set_bit/#return-values","title":"RETURN VALUES","text":"

BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.

All other functions return 1 for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_set_bit/#see-also","title":"SEE ALSO","text":"

BN_num_bytes(3), BN_add(3)

"},{"location":"man3/BN_set_bit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/BN_swap/","title":"BN_swap","text":""},{"location":"man3/BN_swap/#name","title":"NAME","text":"

BN_swap - exchange BIGNUMs

"},{"location":"man3/BN_swap/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_swap(BIGNUM *a, BIGNUM *b);\n
"},{"location":"man3/BN_swap/#description","title":"DESCRIPTION","text":"

BN_swap() exchanges the values of a and b.

"},{"location":"man3/BN_swap/#return-values","title":"RETURN VALUES","text":"

BN_swap() does not return a value.

"},{"location":"man3/BN_swap/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 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.

"},{"location":"man3/BN_zero/","title":"BN_zero","text":""},{"location":"man3/BN_zero/#name","title":"NAME","text":"

BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment operations

"},{"location":"man3/BN_zero/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_zero(BIGNUM *a);\nint BN_one(BIGNUM *a);\n\nconst BIGNUM *BN_value_one(void);\n\nint BN_set_word(BIGNUM *a, BN_ULONG w);\nunsigned BN_ULONG BN_get_word(BIGNUM *a);\n
"},{"location":"man3/BN_zero/#description","title":"DESCRIPTION","text":"

BN_ULONG is a macro that will be an unsigned integral type optimized for the most efficient implementation on the local platform.

BN_zero(), BN_one() and BN_set_word() set a to the values 0, 1 and w respectively. BN_zero() and BN_one() are macros.

BN_value_one() returns a BIGNUM constant of value 1. This constant is useful for use in comparisons and assignment.

BN_get_word() returns a, if it can be represented as a BN_ULONG.

"},{"location":"man3/BN_zero/#return-values","title":"RETURN VALUES","text":"

BN_get_word() returns the value a, or all-bits-set if a cannot be represented as a single integer.

BN_one() and BN_set_word() return 1 on success, 0 otherwise. BN_value_one() returns the constant. BN_zero() never fails and returns no value.

"},{"location":"man3/BN_zero/#bugs","title":"BUGS","text":"

If a BIGNUM is equal to the value of all-bits-set, it will collide with the error condition returned by BN_get_word() which uses that as an error value.

BN_ULONG should probably be a typedef.

"},{"location":"man3/BN_zero/#see-also","title":"SEE ALSO","text":"

BN_bn2bin(3)

"},{"location":"man3/BN_zero/#history","title":"HISTORY","text":"

In OpenSSL 0.9.8, BN_zero() was changed to not return a value; previous versions returned an int.

"},{"location":"man3/BN_zero/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 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.

"},{"location":"man3/BUF_MEM_new/","title":"BUF_MEM_new","text":""},{"location":"man3/BUF_MEM_new/#name","title":"NAME","text":"

BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, BUF_MEM_grow_clean, BUF_reverse - simple character array structure

"},{"location":"man3/BUF_MEM_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/buffer.h>\n\nBUF_MEM *BUF_MEM_new(void);\n\nBUF_MEM *BUF_MEM_new_ex(unsigned long flags);\n\nvoid BUF_MEM_free(BUF_MEM *a);\n\nint BUF_MEM_grow(BUF_MEM *str, int len);\nsize_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);\n\nvoid BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);\n
"},{"location":"man3/BUF_MEM_new/#description","title":"DESCRIPTION","text":"

The buffer library handles simple character arrays. Buffers are used for various purposes in the library, most notably memory BIOs.

BUF_MEM_new() allocates a new buffer of zero size.

BUF_MEM_new_ex() allocates a buffer with the specified flags. The flag BUF_MEM_FLAG_SECURE specifies that the data pointer should be allocated on the secure heap; see CRYPTO_secure_malloc(3).

BUF_MEM_free() frees up an already existing buffer. The data is zeroed before freeing up in case the buffer contains sensitive data. If the argument is NULL, nothing is done.

BUF_MEM_grow() changes the size of an already existing buffer to len. Any data already in the buffer is preserved if it increases in size.

BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd or additionally-allocated memory to zero.

BUF_reverse() reverses size bytes at in into out. If in is NULL, the array is reversed in-place.

"},{"location":"man3/BUF_MEM_new/#return-values","title":"RETURN VALUES","text":"

BUF_MEM_new() returns the buffer or NULL on error.

BUF_MEM_free() has no return value.

BUF_MEM_grow() and BUF_MEM_grow_clean() return zero on error or the new size (i.e., len).

"},{"location":"man3/BUF_MEM_new/#see-also","title":"SEE ALSO","text":"

bio(7), CRYPTO_secure_malloc(3).

"},{"location":"man3/BUF_MEM_new/#history","title":"HISTORY","text":"

The BUF_MEM_new_ex() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BUF_MEM_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/CMAC_CTX/","title":"CMAC_CTX","text":""},{"location":"man3/CMAC_CTX/#name","title":"NAME","text":"

CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final, CMAC_resume - create cipher-based message authentication codes

"},{"location":"man3/CMAC_CTX/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cmac.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be disabled entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7).

typedef struct CMAC_CTX_st CMAC_CTX;\n\nCMAC_CTX *CMAC_CTX_new(void);\nvoid CMAC_CTX_cleanup(CMAC_CTX *ctx);\nvoid CMAC_CTX_free(CMAC_CTX *ctx);\nEVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);\nint CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);\nint CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,\n              const EVP_CIPHER *cipher, ENGINE *impl);\nint CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);\nint CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);\nint CMAC_resume(CMAC_CTX *ctx);\n
"},{"location":"man3/CMAC_CTX/#description","title":"DESCRIPTION","text":"

The low-level MAC functions documented on this page are deprecated. Applications should use the new EVP_MAC(3) interface. Specifically, utilize the following functions for MAC operations:

Alternatively, for a single-step MAC computation, use the EVP_Q_mac(3) function.

The CMAC_CTX type is a structure used for the provision of CMAC (Cipher-based Message Authentication Code) operations.

CMAC_CTX_new() creates a new CMAC_CTX structure and returns a pointer to it.

CMAC_CTX_cleanup() resets the CMAC_CTX structure, clearing any internal data but not freeing the structure itself.

CMAC_CTX_free() frees the CMAC_CTX structure and any associated resources. If the argument is NULL, no action is taken.

CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal EVP_CIPHER_CTX structure within the CMAC_CTX.

CMAC_CTX_copy() copies the state from one CMAC_CTX structure to another.

CMAC_Init() initializes the CMAC_CTX structure for a new CMAC calculation with the specified key, key length, and cipher type. Optionally, an ENGINE can be provided.

CMAC_Update() processes data to be included in the CMAC calculation. This function can be called multiple times to update the context with additional data.

CMAC_Final() finalizes the CMAC calculation and retrieves the resulting MAC value. The output is stored in the provided buffer, and the length is stored in the variable pointed to by poutlen. To determine the required buffer size, call with out set to NULL, which stores only the length in poutlen. Allocate a buffer of this size and call CMAC_Final() again with the allocated buffer to retrieve the MAC.

CMAC_resume() resumes a previously finalized CMAC calculation, allowing additional data to be processed and a new MAC to be generated.

"},{"location":"man3/CMAC_CTX/#return-values","title":"RETURN VALUES","text":"

CMAC_CTX_new() returns a pointer to a new CMAC_CTX structure or NULL if an error occurs.

CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal EVP_CIPHER_CTX structure, or NULL if an error occurs.

CMAC_CTX_copy(), CMAC_Init(), CMAC_Update(), CMAC_Final() and CMAC_resume() return 1 for success or 0 if an error occurs.

"},{"location":"man3/CMAC_CTX/#history","title":"HISTORY","text":"

All functions described here were deprecated in OpenSSL 3.0. For replacements, see EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3), EVP_MAC_update(3), and EVP_MAC_final(3).

"},{"location":"man3/CMAC_CTX/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/CMS_EncryptedData_decrypt/","title":"CMS_EncryptedData_decrypt","text":""},{"location":"man3/CMS_EncryptedData_decrypt/#name","title":"NAME","text":"

CMS_EncryptedData_decrypt, CMS_EnvelopedData_decrypt - Decrypt CMS EncryptedData or EnvelopedData

"},{"location":"man3/CMS_EncryptedData_decrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_EncryptedData_decrypt(CMS_ContentInfo *cms,\n                              const unsigned char *key, size_t keylen,\n                              BIO *dcont, BIO *out, unsigned int flags);\n\nBIO *CMS_EnvelopedData_decrypt(CMS_EnvelopedData *env, BIO *detached_data,\n                               EVP_PKEY *pkey, X509 *cert,\n                               ASN1_OCTET_STRING *secret, unsigned int flags,\n                               OSSL_LIB_CTX *libctx, const char *propq);\n
"},{"location":"man3/CMS_EncryptedData_decrypt/#description","title":"DESCRIPTION","text":"

CMS_EncryptedData_decrypt() decrypts a cms EncryptedData object using the symmetric key of size keylen bytes. out is a BIO to write the content to and flags is an optional set of flags. dcont is used in the rare case where the encrypted content is detached. It will normally be set to NULL.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

CMS_EnvelopedData_decrypt() decrypts, similarly to CMS_decrypt(3), a CMS EnvelopedData object env using the symmetric key secret if it is not NULL, otherwise the private key of the recipient pkey. If pkey is given, it is recommended to provide also the associated certificate in cert - see CMS_decrypt(3) and the NOTES on cert there. The optional parameters flags and dcont are used as described above. The optional parameters library context libctx and property query propq are used when retrieving algorithms from providers.

"},{"location":"man3/CMS_EncryptedData_decrypt/#return-values","title":"RETURN VALUES","text":"

CMS_EncryptedData_decrypt() returns 0 if an error occurred otherwise returns 1.

CMS_EnvelopedData_decrypt() returns NULL if an error occurred, otherwise a BIO containing the decypted content.

"},{"location":"man3/CMS_EncryptedData_decrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_EncryptedData_encrypt(3), CMS_decrypt(3)

"},{"location":"man3/CMS_EncryptedData_decrypt/#history","title":"HISTORY","text":"

CMS_EnvelopedData_decrypt() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_EncryptedData_decrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CMS_EncryptedData_encrypt/","title":"CMS_EncryptedData_encrypt","text":""},{"location":"man3/CMS_EncryptedData_encrypt/#name","title":"NAME","text":"

CMS_EncryptedData_encrypt_ex, CMS_EncryptedData_encrypt - Create CMS EncryptedData

"},{"location":"man3/CMS_EncryptedData_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_EncryptedData_encrypt_ex(BIO *in,\n                                              const EVP_CIPHER *cipher,\n                                              const unsigned char *key,\n                                              size_t keylen,\n                                              unsigned int flags,\n                                              OSSL_LIB_CTX *ctx,\n                                              const char *propq);\n\nCMS_ContentInfo *CMS_EncryptedData_encrypt(BIO *in,\n    const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen,\n    unsigned int flags);\n
"},{"location":"man3/CMS_EncryptedData_encrypt/#description","title":"DESCRIPTION","text":"

CMS_EncryptedData_encrypt_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_encrypted. in is a BIO containing the data to encrypt using cipher and the encryption key key of size keylen bytes. The library context libctx and the property query propq are used when retrieving algorithms from providers. flags is a set of optional flags.

The flags field supports the options CMS_DETACHED, CMS_STREAM and CMS_PARTIAL. Internally CMS_final() is called unless CMS_STREAM and/or CMS_PARTIAL is specified.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_EncryptedData_encrypt() is similar to CMS_EncryptedData_encrypt_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_EncryptedData_encrypt/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_EncryptedData_encrypt_ex() and CMS_EncryptedData_encrypt() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_EncryptedData_encrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3), CMS_EncryptedData_decrypt(3)

"},{"location":"man3/CMS_EncryptedData_encrypt/#history","title":"HISTORY","text":"

The CMS_EncryptedData_encrypt_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_EncryptedData_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/CMS_EnvelopedData_create/","title":"CMS_EnvelopedData_create","text":""},{"location":"man3/CMS_EnvelopedData_create/#name","title":"NAME","text":"

CMS_EnvelopedData_create_ex, CMS_EnvelopedData_create, CMS_AuthEnvelopedData_create, CMS_AuthEnvelopedData_create_ex - Create CMS envelope

"},{"location":"man3/CMS_EnvelopedData_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *\nCMS_EnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,\n                            const char *propq);\nCMS_ContentInfo *CMS_EnvelopedData_create(const EVP_CIPHER *cipher);\n\nCMS_ContentInfo *\nCMS_AuthEnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,\n                                const char *propq);\nCMS_ContentInfo *CMS_AuthEnvelopedData_create(const EVP_CIPHER *cipher);\n
"},{"location":"man3/CMS_EnvelopedData_create/#description","title":"DESCRIPTION","text":"

CMS_EnvelopedData_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_enveloped. cipher is the symmetric cipher to use. The library context libctx and the property query propq are used when retrieving algorithms from providers.

CMS_AuthEnvelopedData_create_ex() creates a CMS_ContentInfo structure with a type NID_id_smime_ct_authEnvelopedData. cipher is the symmetric AEAD cipher to use. Currently only AES variants with GCM mode are supported. The library context libctx and the property query propq are used when retrieving algorithms from providers.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters.

The recipients can be added later using CMS_add1_recipient_cert(3) or CMS_add0_recipient_key(3).

The CMS_ContentInfo structure needs to be finalized using CMS_final(3) and then freed using CMS_ContentInfo_free(3).

CMS_EnvelopedData_create() and CMS_AuthEnvelopedData_create() are similar to CMS_EnvelopedData_create_ex() and CMS_AuthEnvelopedData_create_ex() but use default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_EnvelopedData_create/#notes","title":"NOTES","text":"

Although CMS_EnvelopedData_create_ex(), and CMS_EnvelopedData_create(), CMS_AuthEnvelopedData_create_ex(), and CMS_AuthEnvelopedData_create() allocate a new CMS_ContentInfo structure, they are not usually used in applications. The wrappers CMS_encrypt(3) and CMS_decrypt(3) are often used instead.

"},{"location":"man3/CMS_EnvelopedData_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_EnvelopedData_create_ex(), CMS_EnvelopedData_create(), CMS_AuthEnvelopedData_create_ex(), and CMS_AuthEnvelopedData_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_EnvelopedData_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_encrypt(3), CMS_decrypt(3), CMS_final(3)

"},{"location":"man3/CMS_EnvelopedData_create/#history","title":"HISTORY","text":"

The CMS_EnvelopedData_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_EnvelopedData_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/CMS_add0_cert/","title":"CMS_add0_cert","text":""},{"location":"man3/CMS_add0_cert/#name","title":"NAME","text":"

CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls - CMS certificate and CRL utility functions

"},{"location":"man3/CMS_add0_cert/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);\nint CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);\nSTACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);\n\nint CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);\nint CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);\nSTACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_add0_cert/#description","title":"DESCRIPTION","text":"

CMS_add0_cert() and CMS_add1_cert() add certificate cert to cms unless it is already present. This is used by CMS_sign_ex(3) and CMS_sign(3) and may be used before calling CMS_verify(3) to help chain building in certificate validation. As the 0 implies, CMS_add0_cert() adds cert internally to cms and on success it must not be freed up by the caller. In contrast, the caller of CMS_add1_cert() must free cert. cms must be of type signed data or (authenticated) enveloped data. For signed data, such a certificate can be used when signing or verifying to fill in the signer certificate or to provide an extra CA certificate that may be needed for chain building in certificate validation.

CMS_get1_certs() returns all certificates in cms.

CMS_add0_crl() and CMS_add1_crl() add CRL crl to cms. cms must be of type signed data or (authenticated) enveloped data. For signed data, such a CRL may be used in certificate validation with CMS_verify(3). It may be given both for inclusion when signing a CMS message and when verifying a signed CMS message.

CMS_get1_crls() returns all CRLs in cms.

"},{"location":"man3/CMS_add0_cert/#notes","title":"NOTES","text":"

The CMS_ContentInfo structure cms must be of type signed data or enveloped data or authenticated enveloped data or an error will be returned.

For signed data, certificates and CRLs are added to the certificates and crls fields of SignedData structure. For enveloped data they are added to OriginatorInfo.

"},{"location":"man3/CMS_add0_cert/#return-values","title":"RETURN VALUES","text":"

CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return 1 for success and 0 for failure.

CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs, which is empty if there are none. They return NULL on error. Besides out-of-memory, the only error which will occur in practice is if the cms type is invalid.

"},{"location":"man3/CMS_add0_cert/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_sign_ex(3), CMS_verify(3), CMS_encrypt(3)

"},{"location":"man3/CMS_add0_cert/#history","title":"HISTORY","text":"

CMS_add0_cert() and CMS_add1_cert() have been changed in OpenSSL 3.2 not to throw an error if a certificate to be added is already present.

"},{"location":"man3/CMS_add0_cert/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2024 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.

"},{"location":"man3/CMS_add1_recipient_cert/","title":"CMS_add1_recipient_cert","text":""},{"location":"man3/CMS_add1_recipient_cert/#name","title":"NAME","text":"

CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure

"},{"location":"man3/CMS_add1_recipient_cert/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,\n                                      EVP_PKEY *originatorPrivKey,\n                                      X509 *originator, unsigned int flags);\n\nCMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,\n                                           X509 *recip, unsigned int flags);\n\nCMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,\n                                          unsigned char *key, size_t keylen,\n                                          unsigned char *id, size_t idlen,\n                                          ASN1_GENERALIZEDTIME *date,\n                                          ASN1_OBJECT *otherTypeId,\n                                          ASN1_TYPE *otherType);\n
"},{"location":"man3/CMS_add1_recipient_cert/#description","title":"DESCRIPTION","text":"

CMS_add1_recipient() adds recipient recip and provides the originator pkey originatorPrivKey and originator certificate originator to CMS_ContentInfo. The originator-related fields are relevant only in case when the keyAgreement method of providing of the shared key is in use.

CMS_add1_recipient_cert() adds recipient recip to CMS_ContentInfo enveloped data structure cms as a KeyTransRecipientInfo structure.

CMS_add0_recipient_key() adds symmetric key key of length keylen using wrapping algorithm nid, identifier id of length idlen and optional values date, otherTypeId and otherType to CMS_ContentInfo enveloped data structure cms as a KEKRecipientInfo structure.

The CMS_ContentInfo structure should be obtained from an initial call to CMS_encrypt() with the flag CMS_PARTIAL set.

"},{"location":"man3/CMS_add1_recipient_cert/#notes","title":"NOTES","text":"

The main purpose of this function is to provide finer control over a CMS enveloped data structure where the simpler CMS_encrypt() function defaults are not appropriate. For example if one or more KEKRecipientInfo structures need to be added. New attributes can also be added using the returned CMS_RecipientInfo structure and the CMS attribute utility functions.

OpenSSL will by default identify recipient certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if all recipient certificates do not have a subject key identifier extension.

Currently only AES based key wrapping algorithms are supported for nid, specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. If nid is set to NID_undef then an AES wrap algorithm will be used consistent with keylen.

"},{"location":"man3/CMS_add1_recipient_cert/#return-values","title":"RETURN VALUES","text":"

CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal pointer to the CMS_RecipientInfo structure just added or NULL if an error occurs.

"},{"location":"man3/CMS_add1_recipient_cert/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3), CMS_final(3),

"},{"location":"man3/CMS_add1_recipient_cert/#history","title":"HISTORY","text":"

CMS_add1_recipient_cert and CMS_add0_recipient_key were added in OpenSSL 3.0.

"},{"location":"man3/CMS_add1_recipient_cert/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CMS_add1_signer/","title":"CMS_add1_signer","text":""},{"location":"man3/CMS_add1_signer/#name","title":"NAME","text":"

CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure

"},{"location":"man3/CMS_add1_signer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert,\n                                EVP_PKEY *pkey, const EVP_MD *md,\n                                unsigned int flags);\n\nint CMS_SignerInfo_sign(CMS_SignerInfo *si);\n
"},{"location":"man3/CMS_add1_signer/#description","title":"DESCRIPTION","text":"

CMS_add1_signer() adds a signer with certificate signcert and private key pkey using message digest md to CMS_ContentInfo SignedData structure cms.

The CMS_ContentInfo structure should be obtained from an initial call to CMS_sign() with the flag CMS_PARTIAL set or in the case or re-signing a valid CMS_ContentInfo SignedData structure.

If the md parameter is NULL then the default digest for the public key algorithm will be used.

Unless the CMS_REUSE_DIGEST flag is set the returned CMS_ContentInfo structure is not complete and must be finalized either by streaming (if applicable) or a call to CMS_final().

The CMS_SignerInfo_sign() function explicitly signs a CMS_SignerInfo structure, its main use is when the CMS_REUSE_DIGEST and CMS_PARTIAL flags are both set.

"},{"location":"man3/CMS_add1_signer/#notes","title":"NOTES","text":"

The main purpose of CMS_add1_signer() is to provide finer control over a CMS signed data structure where the simpler CMS_sign() function defaults are not appropriate. For example if multiple signers or non default digest algorithms are needed. New attributes can also be added using the returned CMS_SignerInfo structure and the CMS attribute utility functions or the CMS signed receipt request functions.

Any of the following flags (ored together) can be passed in the flags parameter.

If CMS_REUSE_DIGEST is set then an attempt is made to copy the content digest value from the CMS_ContentInfo structure: to add a signer to an existing structure. An error occurs if a matching digest value cannot be found to copy. The returned CMS_ContentInfo structure will be valid and finalized when this flag is set.

If CMS_PARTIAL is set in addition to CMS_REUSE_DIGEST then the CMS_SignerInfo structure will not be finalized so additional attributes can be added. In this case an explicit call to CMS_SignerInfo_sign() is needed to finalize it.

If CMS_NOCERTS is set the signer's certificate will not be included in the CMS_ContentInfo structure, the signer's certificate must still be supplied in the signcert parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message.

The SignedData structure includes several CMS signedAttributes including the signing time, the CMS content type and the supported list of ciphers in an SMIMECapabilities attribute. If CMS_NOATTR is set then no signedAttributes will be used. If CMS_NOSMIMECAP is set then just the SMIMECapabilities are omitted.

OpenSSL will by default identify signing certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if the signing certificate does not have a subject key identifier extension.

If present the SMIMECapabilities attribute indicates support for the following algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded.

CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added, this can be used to set additional attributes before it is finalized.

"},{"location":"man3/CMS_add1_signer/#return-values","title":"RETURN VALUES","text":"

CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added or NULL if an error occurs.

CMS_SignerInfo_sign() returns 1 on success, 0 on failure.

"},{"location":"man3/CMS_add1_signer/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_final(3),

"},{"location":"man3/CMS_add1_signer/#copyright","title":"COPYRIGHT","text":"

Copyright 2014-2016 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.

"},{"location":"man3/CMS_compress/","title":"CMS_compress","text":""},{"location":"man3/CMS_compress/#name","title":"NAME","text":"

CMS_compress - create a CMS CompressedData structure

"},{"location":"man3/CMS_compress/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);\n
"},{"location":"man3/CMS_compress/#description","title":"DESCRIPTION","text":"

CMS_compress() creates and returns a CMS CompressedData structure. comp_nid is the compression algorithm to use or NID_undef to use the default algorithm (zlib compression). in is the content to be compressed. flags is an optional set of flags.

The only currently supported compression algorithm is zlib using the NID NID_zlib_compression.

If zlib support is not compiled into OpenSSL then CMS_compress() will return an error.

If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it. If CMS_BINARY is set then CMS_TEXT is ignored.

If the CMS_STREAM flag is set a partial CMS_ContentInfo structure is returned suitable for streaming I/O: no data is read from the BIO in.

The compressed data is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS().

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

Additional compression parameters such as the zlib compression level cannot currently be set.

"},{"location":"man3/CMS_compress/#return-values","title":"RETURN VALUES","text":"

CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_compress/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_uncompress(3)

"},{"location":"man3/CMS_compress/#history","title":"HISTORY","text":"

The CMS_STREAM flag was added in OpenSSL 1.0.0.

"},{"location":"man3/CMS_compress/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/CMS_data_create/","title":"CMS_data_create","text":""},{"location":"man3/CMS_data_create/#name","title":"NAME","text":"

CMS_data_create_ex, CMS_data_create - Create CMS Data object

"},{"location":"man3/CMS_data_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_data_create_ex(BIO *in, unsigned int flags,\n                                    OSSL_LIB_CTX *libctx, const char *propq);\nCMS_ContentInfo *CMS_data_create(BIO *in, unsigned int flags);\n
"},{"location":"man3/CMS_data_create/#description","title":"DESCRIPTION","text":"

CMS_data_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_data. The data is supplied via the in BIO. The library context libctx and the property query propq are used when retrieving algorithms from providers. The flags field supports the CMS_STREAM flag. Internally CMS_final() is called unless CMS_STREAM is specified.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_data_create() is similar to CMS_data_create_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_data_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_data_create_ex() and CMS_data_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_data_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3)

"},{"location":"man3/CMS_data_create/#history","title":"HISTORY","text":"

The CMS_data_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_data_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/CMS_decrypt/","title":"CMS_decrypt","text":""},{"location":"man3/CMS_decrypt/#name","title":"NAME","text":"

CMS_decrypt, CMS_decrypt_set1_pkey_and_peer, CMS_decrypt_set1_pkey, CMS_decrypt_set1_password - decrypt content from a CMS envelopedData structure

"},{"location":"man3/CMS_decrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,\n                BIO *dcont, BIO *out, unsigned int flags);\nint CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms,\n                EVP_PKEY *pk, X509 *cert, X509 *peer);\nint CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);\nint CMS_decrypt_set1_password(CMS_ContentInfo *cms,\n                              unsigned char *pass, ossl_ssize_t passlen);\n
"},{"location":"man3/CMS_decrypt/#description","title":"DESCRIPTION","text":"

CMS_decrypt() extracts the decrypted content from a CMS EnvelopedData or AuthEnvelopedData structure. It uses CMS_decrypt_set1_pkey() to decrypt the content with the recipient private key pkey if pkey is not NULL. In this case, the associated certificate is recommended to provide in cert - see the NOTES below. out is a BIO to write the content to and flags is an optional set of flags. If pkey is NULL the function assumes that decryption was already done (e.g., using CMS_decrypt_set1_pkey() or CMS_decrypt_set1_password()) and just provides the content unless cert, dcont, and out are NULL as well. The dcont parameter is used in the rare case where the encrypted content is detached. It will normally be set to NULL.

CMS_decrypt_set1_pkey_and_peer() decrypts the CMS_ContentInfo structure cms using the private key pkey, the corresponding certificate cert, which is recommended but may be NULL, and the (optional) originator certificate peer. On success, it also records in cms the decryption key pkey, and then should be followed by CMS_decrypt(cms, NULL, NULL, dcont, out, flags). This call deallocates any decryption key stored in cms.

CMS_decrypt_set1_pkey() is the same as CMS_decrypt_set1_pkey_and_peer() with peer being NULL.

CMS_decrypt_set1_password() decrypts the CMS_ContentInfo structure cms using the secret pass of length passlen. On success, it also records in cms the decryption key used, and then should be followed by CMS_decrypt(cms, NULL, NULL, dcont, out, flags). This call deallocates any decryption key stored in cms.

"},{"location":"man3/CMS_decrypt/#notes","title":"NOTES","text":"

Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the CMS structure.

If cert is set to NULL all possible recipients are tried. This case however is problematic. To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or not. If no recipient succeeds then a random symmetric key is used to decrypt the content: this will typically output garbage and may (but is not guaranteed to) ultimately return a padding error only. If CMS_decrypt() just returned an error when all recipient encrypted keys failed to decrypt an attacker could use this in a timing attack. If the special flag CMS_DEBUG_DECRYPT is set then the above behaviour is modified and an error is returned if no recipient encrypted key can be decrypted without generating a random content encryption key. Applications should use this flag with extreme caution especially in automated gateways as it can leave them open to attack.

It is possible to determine the correct recipient key by other means (for example looking them up in a database) and setting them in the CMS structure in advance using the CMS utility functions such as CMS_set1_pkey(), or use CMS_decrypt_set1_password() if the recipient has a symmetric key. In these cases both cert and pkey should be set to NULL.

To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and cert and pkey set to NULL.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

"},{"location":"man3/CMS_decrypt/#return-values","title":"RETURN VALUES","text":"

CMS_decrypt(), CMS_decrypt_set1_pkey_and_peer(), CMS_decrypt_set1_pkey(), and CMS_decrypt_set1_password() return either 1 for success or 0 for failure. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_decrypt/#bugs","title":"BUGS","text":"

The set1_ part of these function names is misleading and should better read: with_.

The lack of single pass processing and the need to hold all data in memory as mentioned in CMS_verify() also applies to CMS_decrypt().

"},{"location":"man3/CMS_decrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_encrypt(3)

"},{"location":"man3/CMS_decrypt/#history","title":"HISTORY","text":"

CMS_decrypt_set1_pkey_and_peer() and CMS_decrypt_set1_password() were added in OpenSSL 3.0.

"},{"location":"man3/CMS_decrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CMS_digest_create/","title":"CMS_digest_create","text":""},{"location":"man3/CMS_digest_create/#name","title":"NAME","text":"

CMS_digest_create_ex, CMS_digest_create - Create CMS DigestedData object

"},{"location":"man3/CMS_digest_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_digest_create_ex(BIO *in, const EVP_MD *md,\n                                      unsigned int flags, OSSL_LIB_CTX *ctx,\n                                      const char *propq);\n\nCMS_ContentInfo *CMS_digest_create(BIO *in, const EVP_MD *md,\n                                   unsigned int flags);\n
"},{"location":"man3/CMS_digest_create/#description","title":"DESCRIPTION","text":"

CMS_digest_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_digest. The data supplied via the in BIO is digested using md. The library context libctx and the property query propq are used when retrieving algorithms from providers. The flags field supports the CMS_DETACHED and CMS_STREAM flags, Internally CMS_final() is called unless CMS_STREAM is specified.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_digest_create() is similar to CMS_digest_create_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_digest_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_digest_create_ex() and CMS_digest_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_digest_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3)>

"},{"location":"man3/CMS_digest_create/#history","title":"HISTORY","text":"

The CMS_digest_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_digest_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/CMS_encrypt/","title":"CMS_encrypt","text":""},{"location":"man3/CMS_encrypt/#name","title":"NAME","text":"

CMS_encrypt_ex, CMS_encrypt - create a CMS envelopedData structure

"},{"location":"man3/CMS_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_encrypt_ex(STACK_OF(X509) *certs, BIO *in,\n                                const EVP_CIPHER *cipher, unsigned int flags,\n                                OSSL_LIB_CTX *libctx, const char *propq);\nCMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in,\n                             const EVP_CIPHER *cipher, unsigned int flags);\n
"},{"location":"man3/CMS_encrypt/#description","title":"DESCRIPTION","text":"

CMS_encrypt_ex() creates and returns a CMS EnvelopedData or AuthEnvelopedData structure. certs is a list of recipient certificates. in is the content to be encrypted. cipher is the symmetric cipher to use. flags is an optional set of flags. The library context libctx and the property query propq are used internally when retrieving algorithms from providers.

Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this function.

EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because most clients will support it.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters. If the cipher mode is GCM, then an AuthEnvelopedData structure containing MAC is used. Otherwise an EnvelopedData structure is used. Currently the AES variants with GCM mode are the only supported AEAD algorithms.

Many browsers implement a \"sign and encrypt\" option which is simply an S/MIME envelopedData containing an S/MIME signed message. This can be readily produced by storing the S/MIME signed message in a memory BIO and passing it to CMS_encrypt().

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it. If CMS_BINARY is set then CMS_TEXT is ignored.

OpenSSL will by default identify recipient certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if all recipient certificates do not have a subject key identifier extension.

If the CMS_STREAM flag is set a partial CMS_ContentInfo structure is returned suitable for streaming I/O: no data is read from the BIO in.

If the CMS_PARTIAL flag is set a partial CMS_ContentInfo structure is returned to which additional recipients and attributes can be added before finalization.

The data being encrypted is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS().

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

The recipients specified in certs use a CMS KeyTransRecipientInfo info structure. KEKRecipientInfo is also supported using the flag CMS_PARTIAL and CMS_add0_recipient_key().

The parameter certs may be NULL if CMS_PARTIAL is set and recipients added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().

CMS_encrypt() is similar to CMS_encrypt_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_encrypt/#return-values","title":"RETURN VALUES","text":"

CMS_encrypt_ex() and CMS_encrypt() return either a CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_encrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3)

"},{"location":"man3/CMS_encrypt/#history","title":"HISTORY","text":"

The function CMS_encrypt_ex() was added in OpenSSL 3.0.

The CMS_STREAM flag was first supported in OpenSSL 1.0.0.

"},{"location":"man3/CMS_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CMS_final/","title":"CMS_final","text":""},{"location":"man3/CMS_final/#name","title":"NAME","text":"

CMS_final, CMS_final_digest - finalise a CMS_ContentInfo structure

"},{"location":"man3/CMS_final/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);\nint CMS_final_digest(CMS_ContentInfo *cms, const unsigned char *md,\n                     unsigned int mdlen, BIO *dcont, unsigned int flags);\n
"},{"location":"man3/CMS_final/#description","title":"DESCRIPTION","text":"

CMS_final() finalises the structure cms. Its purpose is to perform any operations necessary on cms (digest computation for example) and set the appropriate fields. The parameter data contains the content to be processed. The dcont parameter contains a BIO to write content to after processing: this is only used with detached data and will usually be set to NULL.

CMS_final_digest() finalises the structure cms using a pre-computed digest, rather than computing the digest from the original data.

"},{"location":"man3/CMS_final/#notes","title":"NOTES","text":"

These functions will normally be called when the CMS_PARTIAL flag is used. It should only be used when streaming is not performed because the streaming I/O functions perform finalisation operations internally.

To sign a pre-computed digest, CMS_sign(3) or CMS_sign_ex() is called with the data parameter set to NULL before the CMS structure is finalised with the digest provided to CMS_final_digest() in binary form. When signing a pre-computed digest, the security relies on the digest and its computation from the original message being trusted.

"},{"location":"man3/CMS_final/#return-values","title":"RETURN VALUES","text":"

CMS_final() and CMS_final_digest() return 1 for success or 0 for failure.

"},{"location":"man3/CMS_final/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_encrypt(3)

"},{"location":"man3/CMS_final/#history","title":"HISTORY","text":"

CMS_final_digest() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_final/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2022 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.

"},{"location":"man3/CMS_get0_RecipientInfos/","title":"CMS_get0_RecipientInfos","text":""},{"location":"man3/CMS_get0_RecipientInfos/#name","title":"NAME","text":"

CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kari_set0_pkey_and_peer, CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines

"},{"location":"man3/CMS_get0_RecipientInfos/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nSTACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);\nint CMS_RecipientInfo_type(CMS_RecipientInfo *ri);\n\nint CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,\n                                          ASN1_OCTET_STRING **keyid,\n                                          X509_NAME **issuer,\n                                          ASN1_INTEGER **sno);\nint CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);\nint CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);\nint CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,\n                                              EVP_PKEY *pk, X509 *peer);\nint CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);\nint CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,\n                                    ASN1_OCTET_STRING **pid,\n                                    ASN1_GENERALIZEDTIME **pdate,\n                                    ASN1_OBJECT **potherid,\n                                    ASN1_TYPE **pothertype);\nint CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,\n                                   const unsigned char *id, size_t idlen);\nint CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,\n                               unsigned char *key, size_t keylen);\n\nint CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);\nint CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);\n
"},{"location":"man3/CMS_get0_RecipientInfos/#description","title":"DESCRIPTION","text":"

The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo structures associated with a CMS EnvelopedData structure.

CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure ri. It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.

CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient identifier associated with a specific CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in keyid or both issuer name and serial number in issuer and sno.

CMS_RecipientInfo_ktri_cert_cmp() compares the certificate cert against the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. It returns zero if the comparison is successful and non zero if not.

CMS_RecipientInfo_set0_pkey() associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS.

CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key pkey and peer certificate peer with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE.

CMS_RecipientInfo_kari_set0_pkey() associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE.

CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the CMS_RecipientInfo structure ri which must be of type CMS_RECIPINFO_KEK. Any of the remaining parameters can be NULL if the application is not interested in the value of a field. Where a field is optional and absent NULL will be written to the corresponding parameter. The keyEncryptionAlgorithm field is written to palg, the keyIdentifier field is written to pid, the date field if present is written to pdate, if the other field is present the components keyAttrId and keyAttr are written to parameters potherid and pothertype.

CMS_RecipientInfo_kekri_id_cmp() compares the ID in the id and idlen parameters against the keyIdentifier CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is successful and non zero if not.

CMS_RecipientInfo_set0_key() associates the symmetric key key of length keylen with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK.

CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure ri in structure cms. A key must have been associated with the structure first.

CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure ri in structure cms. A key must have been associated with the structure first and the content encryption key must be available: for example by a previous call to CMS_RecipientInfo_decrypt().

"},{"location":"man3/CMS_get0_RecipientInfos/#notes","title":"NOTES","text":"

The main purpose of these functions is to enable an application to lookup recipient keys using any appropriate technique when the simpler method of CMS_decrypt() is not appropriate.

In typical usage and application will retrieve all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and check the type of each using CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure can be ignored or its key identifier data retrieved using an appropriate function. Then if the corresponding secret or private key can be obtained by any appropriate means it can then associated with the structure and CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called with a NULL key to decrypt the enveloped content.

The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an existing enveloped data structure. Typically an application will first decrypt an appropriate CMS_RecipientInfo structure to make the content encrypt key available, it will then add a new recipient using a function such as CMS_add1_recipient_cert() and finally encrypt the content encryption key using CMS_RecipientInfo_encrypt().

"},{"location":"man3/CMS_get0_RecipientInfos/#return-values","title":"RETURN VALUES","text":"

CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if an error occurs.

CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.

CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero otherwise.

Any error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_get0_RecipientInfos/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3)

"},{"location":"man3/CMS_get0_RecipientInfos/#history","title":"HISTORY","text":"

CMS_RecipientInfo_kari_set0_pkey_and_peer and CMS_RecipientInfo_kari_set0_pkey were added in OpenSSL 3.0.

"},{"location":"man3/CMS_get0_RecipientInfos/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CMS_get0_SignerInfos/","title":"CMS_get0_SignerInfos","text":""},{"location":"man3/CMS_get0_SignerInfos/#name","title":"NAME","text":"

CMS_SignerInfo_set1_signer_cert, CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp - CMS signedData signer functions

"},{"location":"man3/CMS_get0_SignerInfos/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nSTACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);\n\nint CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid,\n                                  X509_NAME **issuer, ASN1_INTEGER **sno);\nASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);\nint CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);\nvoid CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);\n
"},{"location":"man3/CMS_get0_SignerInfos/#description","title":"DESCRIPTION","text":"

The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures associated with a CMS signedData structure.

CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier associated with a specific CMS_SignerInfo structure si. Either the keyidentifier will be set in keyid or both issuer name and serial number in issuer and sno.

CMS_SignerInfo_get0_signature() retrieves the signature associated with si in a pointer to an ASN1_OCTET_STRING structure. This pointer returned corresponds to the internal signature value if si so it may be read or modified.

CMS_SignerInfo_cert_cmp() compares the certificate cert against the signer identifier si. It returns zero if the comparison is successful and non zero if not.

CMS_SignerInfo_set1_signer_cert() sets the signers certificate of si to signer.

"},{"location":"man3/CMS_get0_SignerInfos/#notes","title":"NOTES","text":"

The main purpose of these functions is to enable an application to lookup signers certificates using any appropriate technique when the simpler method of CMS_verify() is not appropriate.

In typical usage and application will retrieve all CMS_SignerInfo structures using CMS_get0_SignerInfo() and retrieve the identifier information using CMS. It will then obtain the signer certificate by some unspecified means (or return and error if it cannot be found) and set it using CMS_SignerInfo_set1_signer_cert().

Once all signer certificates have been set CMS_verify() can be used.

Although CMS_get0_SignerInfos() can return NULL if an error occurs or if there are no signers this is not a problem in practice because the only error which can occur is if the cms structure is not of type signedData due to application error.

"},{"location":"man3/CMS_get0_SignerInfos/#return-values","title":"RETURN VALUES","text":"

CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there are no signers or an error occurs.

CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.

CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non zero otherwise.

CMS_SignerInfo_set1_signer_cert() does not return a value.

Any error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_get0_SignerInfos/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify(3)

"},{"location":"man3/CMS_get0_SignerInfos/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2018 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.

"},{"location":"man3/CMS_get0_type/","title":"CMS_get0_type","text":""},{"location":"man3/CMS_get0_type/#name","title":"NAME","text":"

CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content

"},{"location":"man3/CMS_get0_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nconst ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);\nint CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);\nconst ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);\nASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_get0_type/#description","title":"DESCRIPTION","text":"

CMS_get0_type() returns the content type of a CMS_ContentInfo structure as an ASN1_OBJECT pointer. An application can then decide how to process the CMS_ContentInfo structure based on this value.

CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo structure. It should be called with CMS functions (such as CMS_sign(3), CMS_encrypt(3)) with the CMS_PARTIAL flag and before the structure is finalised, otherwise the results are undefined.

ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded content type.

CMS_get0_content() returns a pointer to the ASN1_OCTET_STRING pointer containing the embedded content.

"},{"location":"man3/CMS_get0_type/#notes","title":"NOTES","text":"

As the 0 implies CMS_get0_type(), CMS_get0_eContentType() and CMS_get0_content() return internal pointers which should not be freed up. CMS_set1_eContentType() copies the supplied OID and it should be freed up after use.

The ASN1_OBJECT values returned can be converted to an integer NID value using OBJ_obj2nid(). For the currently supported content types the following values are returned:

NID_pkcs7_data\nNID_pkcs7_signed\nNID_pkcs7_digest\nNID_id_smime_ct_compressedData:\nNID_pkcs7_encrypted\nNID_pkcs7_enveloped\n

The return value of CMS_get0_content() is a pointer to the ASN1_OCTET_STRING content pointer. That means that for example:

ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);\n

*pconf could be NULL if there is no embedded content. Applications can access, modify or create the embedded content in a CMS_ContentInfo structure using this function. Applications usually will not need to modify the embedded content as it is normally set by higher level functions.

"},{"location":"man3/CMS_get0_type/#return-values","title":"RETURN VALUES","text":"

CMS_get0_type() and CMS_get0_eContentType() return an ASN1_OBJECT structure.

CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_get0_type/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/CMS_get0_type/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/CMS_get1_ReceiptRequest/","title":"CMS_get1_ReceiptRequest","text":""},{"location":"man3/CMS_get1_ReceiptRequest/#name","title":"NAME","text":"

CMS_ReceiptRequest_create0_ex, CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions

"},{"location":"man3/CMS_get1_ReceiptRequest/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ReceiptRequest *CMS_ReceiptRequest_create0_ex(\n    unsigned char *id, int idlen, int allorfirst,\n    STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo,\n    OSSL_LIB_CTX *libctx);\nCMS_ReceiptRequest *CMS_ReceiptRequest_create0(\n    unsigned char *id, int idlen, int allorfirst,\n    STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);\nint CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);\nint CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);\nvoid CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid,\n                                    int *pallorfirst,\n                                    STACK_OF(GENERAL_NAMES) **plist,\n                                    STACK_OF(GENERAL_NAMES) **prto);\n
"},{"location":"man3/CMS_get1_ReceiptRequest/#description","title":"DESCRIPTION","text":"

CMS_ReceiptRequest_create0_ex() creates a signed receipt request structure. The signedContentIdentifier field is set using id and idlen, or it is set to 32 bytes of pseudo random data if id is NULL. If receiptList is NULL the allOrFirstTier option in receiptsFrom is used and set to the value of the allorfirst parameter. If receiptList is not NULL the receiptList option in receiptsFrom is used. The receiptsTo parameter specifies the receiptsTo field value. The library context libctx is used to find the public random generator.

CMS_ReceiptRequest_create0() is similar to CMS_ReceiptRequest_create0_ex() but uses default values of NULL for the library context libctx.

The CMS_add1_ReceiptRequest() function adds a signed receipt request rr to SignerInfo structure si.

int CMS_get1_ReceiptRequest() looks for a signed receipt request in si, if any is found it is decoded and written to prr.

CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. The signedContentIdentifier is copied to pcid. If the allOrFirstTier option of receiptsFrom is used its value is copied to pallorfirst otherwise the receiptList field is copied to plist. The receiptsTo parameter is copied to prto.

"},{"location":"man3/CMS_get1_ReceiptRequest/#notes","title":"NOTES","text":"

For more details of the meaning of the fields see RFC2634.

The contents of a signed receipt should only be considered meaningful if the corresponding CMS_ContentInfo structure can be successfully verified using CMS_verify().

"},{"location":"man3/CMS_get1_ReceiptRequest/#return-values","title":"RETURN VALUES","text":"

CMS_ReceiptRequest_create0_ex() and CMS_ReceiptRequest_create0() return a signed receipt request structure or NULL if an error occurred.

CMS_add1_ReceiptRequest() returns 1 for success or 0 if an error occurred.

CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and decoded. It returns 0 if a signed receipt request is not present and -1 if it is present but malformed.

"},{"location":"man3/CMS_get1_ReceiptRequest/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_sign_receipt(3), CMS_verify(3) CMS_verify_receipt(3)

"},{"location":"man3/CMS_get1_ReceiptRequest/#history","title":"HISTORY","text":"

The function CMS_ReceiptRequest_create0_ex() was added in OpenSSL 3.0.

"},{"location":"man3/CMS_get1_ReceiptRequest/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2021 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.

"},{"location":"man3/CMS_sign/","title":"CMS_sign","text":""},{"location":"man3/CMS_sign/#name","title":"NAME","text":"

CMS_sign, CMS_sign_ex - create a CMS SignedData structure

"},{"location":"man3/CMS_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey,\n                             STACK_OF(X509) *certs, BIO *data,\n                             unsigned int flags, OSSL_LIB_CTX *ctx,\n                             const char *propq);\nCMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,\n                          BIO *data, unsigned int flags);\n
"},{"location":"man3/CMS_sign/#description","title":"DESCRIPTION","text":"

CMS_sign_ex() creates and returns a CMS SignedData structure. signcert is the certificate to sign with, pkey is the corresponding private key. certs is an optional additional set of certificates to include in the CMS structure (for example any intermediate CAs in the chain). The library context libctx and the property query propq are used when retrieving algorithms from providers. Any or all of these parameters can be NULL, see NOTES below.

The data to be signed is read from BIO data.

flags is an optional set of flags.

CMS_sign() is similar to CMS_sign_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_sign/#notes","title":"NOTES","text":"

Any of the following flags (ored together) can be passed in the flags parameter.

Many S/MIME clients expect the signed content to include valid MIME headers. If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

If CMS_NOCERTS is set the signer's certificate will not be included in the CMS_ContentInfo structure, the signer's certificate must still be supplied in the signcert parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message.

The data being signed is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is used for CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed messages for example.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it.

The SignedData structure includes several CMS signedAttributes including the signing time, the CMS content type and the supported list of ciphers in an SMIMECapabilities attribute. If CMS_NOATTR is set then no signedAttributes will be used. If CMS_NOSMIMECAP is set then just the SMIMECapabilities are omitted.

If present the SMIMECapabilities attribute indicates support for the following algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded.

OpenSSL will by default identify signing certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if the signing certificate does not have a subject key identifier extension.

If the flags CMS_STREAM is set then the returned CMS_ContentInfo structure is just initialized ready to perform the signing operation. The signing is however not performed and the data to be signed is not read from the data parameter. Signing is deferred until after the data has been written. In this way data can be signed in a single pass.

If the CMS_PARTIAL flag is set a partial CMS_ContentInfo structure is output to which additional signers and capabilities can be added before finalization.

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

If a signer is specified it will use the default digest for the signing algorithm. This is SHA1 for both RSA and DSA keys.

If signcert and pkey are NULL then a certificates only CMS structure is output.

The function CMS_sign() is a basic CMS signing function whose output will be suitable for many purposes. For finer control of the output format the certs, signcert and pkey parameters can all be NULL and the CMS_PARTIAL flag set. Then one or more signers can be added using the function CMS_add1_signer(), non default digests can be used and custom attributes added. CMS_final() must then be called to finalize the structure if streaming is not enabled.

"},{"location":"man3/CMS_sign/#bugs","title":"BUGS","text":"

Some attributes such as counter signatures are not supported.

"},{"location":"man3/CMS_sign/#return-values","title":"RETURN VALUES","text":"

CMS_sign_ex() and CMS_sign() return either a valid CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_sign/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify(3)

"},{"location":"man3/CMS_sign/#history","title":"HISTORY","text":"

The CMS_STREAM flag is only supported for detached data in OpenSSL 0.9.8, it is supported for embedded data in OpenSSL 1.0.0 and later.

The CMS_sign_ex() method was added in OpenSSL 3.0.

Since OpenSSL 3.2, CMS_sign_ex() and CMS_sign() ignore any duplicate certificates in their certs argument and no longer throw an error for them.

"},{"location":"man3/CMS_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2023 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.

"},{"location":"man3/CMS_sign_receipt/","title":"CMS_sign_receipt","text":""},{"location":"man3/CMS_sign_receipt/#name","title":"NAME","text":"

CMS_sign_receipt - create a CMS signed receipt

"},{"location":"man3/CMS_sign_receipt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert,\n                                  EVP_PKEY *pkey, STACK_OF(X509) *certs,\n                                  unsigned int flags);\n
"},{"location":"man3/CMS_sign_receipt/#description","title":"DESCRIPTION","text":"

CMS_sign_receipt() creates and returns a CMS signed receipt structure. si is the CMS_SignerInfo structure containing the signed receipt request. signcert is the certificate to sign with, pkey is the corresponding private key. certs is an optional additional set of certificates to include in the CMS structure (for example any intermediate CAs in the chain).

flags is an optional set of flags.

"},{"location":"man3/CMS_sign_receipt/#notes","title":"NOTES","text":"

This functions behaves in a similar way to CMS_sign() except the flag values CMS_DETACHED, CMS_BINARY, CMS_NOATTR, CMS_TEXT and CMS_STREAM are not supported since they do not make sense in the context of signed receipts.

"},{"location":"man3/CMS_sign_receipt/#return-values","title":"RETURN VALUES","text":"

CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_sign_receipt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify_receipt(3), CMS_sign(3)

"},{"location":"man3/CMS_sign_receipt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/CMS_signed_get_attr/","title":"CMS_signed_get_attr","text":""},{"location":"man3/CMS_signed_get_attr/#name","title":"NAME","text":"

CMS_signed_get_attr_count, CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr, CMS_signed_delete_attr, CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ, CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt, CMS_signed_get0_data_by_OBJ, CMS_unsigned_get_attr_count, CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, CMS_unsigned_get_attr, CMS_unsigned_delete_attr, CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ, CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt, CMS_unsigned_get0_data_by_OBJ - CMS signed and unsigned attribute functions

"},{"location":"man3/CMS_signed_get_attr/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_signed_get_attr_count(const CMS_SignerInfo *si);\nint CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid,\n                               int lastpos);\nint CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj,\n                               int lastpos);\nX509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc);\nX509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc);\nint CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);\nint CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si,\n                                const ASN1_OBJECT *obj, int type,\n                                const void *bytes, int len);\nint CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si,\n                                int nid, int type,\n                                const void *bytes, int len);\nint CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si,\n                                const char *attrname, int type,\n                                const void *bytes, int len);\nvoid *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si,\n                                  const ASN1_OBJECT *oid,\n                                  int lastpos, int type);\n\nint CMS_unsigned_get_attr_count(const CMS_SignerInfo *si);\nint CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid,\n                                 int lastpos);\nint CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si,\n                                 const ASN1_OBJECT *obj, int lastpos);\nX509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc);\nX509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc);\nint CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);\nint CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si,\n                                  const ASN1_OBJECT *obj, int type,\n                                  const void *bytes, int len);\nint CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si,\n                                  int nid, int type,\n                                  const void *bytes, int len);\nint CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si,\n                                  const char *attrname, int type,\n                                  const void *bytes, int len);\nvoid *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid,\n                                    int lastpos, int type);\n
"},{"location":"man3/CMS_signed_get_attr/#description","title":"DESCRIPTION","text":"

CMS_signerInfo contains separate attribute lists for signed and unsigned attributes. Each CMS_signed_XXX() function is used for signed attributes, and each CMS_unsigned_XXX() function is used for unsigned attributes. Since the CMS_unsigned_XXX() functions work in the same way as the CMS_signed_XXX() equivalents, only the CMS_signed_XXX() functions are described below.

CMS_signed_get_attr_by_OBJ() finds the location of the first matching object obj in the SignerInfo's si signed attribute list. The search starts at the position after lastpos. If the returned value is positive then it can be used on the next call to CMS_signed_get_attr_by_OBJ() as the value of lastpos in order to iterate through the remaining attributes. lastpos can be set to any negative value on the first call, in order to start searching from the start of the signed attribute list.

CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

CMS_signed_get_attr() returns the X509_ATTRIBUTE object at index loc in the si signed attribute list. loc should be in the range from 0 to CMS_signed_get_attr_count() - 1.

CMS_signed_delete_attr() removes the X509_ATTRIBUTE object at index loc in the si signed attribute list. An error occurs if the si attribute list is NULL.

CMS_signed_add1_attr() pushes a copy of the passed in X509_ATTRIBUTE object to the si signed attribute list. A new signed attribute list is created if required. An error occurs if attr is NULL.

CMS_signed_add1_attr_by_OBJ() creates a new signed X509_ATTRIBUTE using X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new obj with type type and data bytes of length len and then pushes it to the key object's attribute list.

CMS_signed_add1_attr_by_NID() is similar to CMS_signed_add1_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

CMS_signed_add1_attr_by_txt() is similar to CMS_signed_add1_attr_by_OBJ() except that it passes a name attrname associated with the object. See <openssl/obj_mac.h> for a list of SN_* names.

CMS_signed_get0_data_by_OBJ() finds the first attribute in a si signed attributes list that matches the obj starting at index lastpos and returns the data retrieved from the found attributes first ASN1_TYPE object. An error will occur if the attribute type type does not match the type of the ASN1_TYPE object OR if type is either V_ASN1_BOOLEAN or V_ASN1_NULL OR the attribute is not found. If lastpos is less than -1 then an error will occur if there are multiple objects in the signed attribute list that match obj. If lastpos is less than -2 then an error will occur if there is more than one ASN1_TYPE object in the found signed attribute.

Refer to X509_ATTRIBUTE(3) for information related to attributes.

"},{"location":"man3/CMS_signed_get_attr/#return-values","title":"RETURN VALUES","text":"

The CMS_unsigned_XXX() functions return values are similar to those of the equivalent CMS_signed_XXX() functions.

CMS_signed_get_attr_count() returns the number of signed attributes in the SignerInfo si, or -1 if the signed attribute list is NULL.

CMS_signed_get_attr_by_OBJ() returns -1 if either the signed attribute list of si is empty OR if obj is not found, otherwise it returns the location of the obj in the SignerInfo's si signed attribute list.

CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except that it returns -2 if the nid is not known by OpenSSL.

CMS_signed_get_attr() returns either a signed X509_ATTRIBUTE or NULL on error.

CMS_signed_delete_attr() returns either the removed signed X509_ATTRIBUTE or NULL if there is a error.

CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt(), return 1 on success or 0 on error.

CMS_signed_get0_data_by_OBJ() returns the data retrieved from the found signed attributes first ASN1_TYPE object, or NULL if an error occurs.

"},{"location":"man3/CMS_signed_get_attr/#notes","title":"NOTES","text":"

Some attributes are added automatically during the signing process.

Calling CMS_SignerInfo_sign() adds the NID_pkcs9_signingTime signed attribute.

Calling CMS_final(), CMS_final_digest() or CMS_dataFinal() adds the NID_pkcs9_messageDigest signed attribute.

The NID_pkcs9_contentType signed attribute is always added if the NID_pkcs9_signingTime attribute is added.

Calling CMS_sign_ex(), CMS_sign_receipt() or CMS_add1_signer() may add attributes depending on the flags parameter. See CMS_add1_signer(3) for more information.

OpenSSL applies special rules for the following attribute NIDs:

CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt() and the equivalent CMS_unsigned_add1_attrXXX() functions allow duplicate attributes to be added. The attribute rules are not checked during these function calls, and are deferred until the sign or verify process (i.e. during calls to any of CMS_sign_ex(), CMS_sign(), CMS_sign_receipt(), CMS_add1_signer(), CMS_Final(), CMS_dataFinal(), CMS_final_digest(), CMS_verify(), CMS_verify_receipt() or CMS_SignedData_verify()).

For CMS attribute rules see RFC 5652 Section 11. For ESS attribute rules see RFC 2634 Section 1.3.4 and RFC 5035 Section 5.4.

"},{"location":"man3/CMS_signed_get_attr/#see-also","title":"SEE ALSO","text":"

X509_ATTRIBUTE(3)

"},{"location":"man3/CMS_signed_get_attr/#copyright","title":"COPYRIGHT","text":"

Copyright 2023-2024 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.

"},{"location":"man3/CMS_uncompress/","title":"CMS_uncompress","text":""},{"location":"man3/CMS_uncompress/#name","title":"NAME","text":"

CMS_uncompress - uncompress a CMS CompressedData structure

"},{"location":"man3/CMS_uncompress/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);\n
"},{"location":"man3/CMS_uncompress/#description","title":"DESCRIPTION","text":"

CMS_uncompress() extracts and uncompresses the content from a CMS CompressedData structure cms. data is a BIO to write the content to and flags is an optional set of flags.

The dcont parameter is used in the rare case where the compressed content is detached. It will normally be set to NULL.

"},{"location":"man3/CMS_uncompress/#notes","title":"NOTES","text":"

The only currently supported compression algorithm is zlib: if the structure indicates the use of any other algorithm an error is returned.

If zlib support is not compiled into OpenSSL then CMS_uncompress() will always return an error.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

"},{"location":"man3/CMS_uncompress/#return-values","title":"RETURN VALUES","text":"

CMS_uncompress() returns either 1 for success or 0 for failure. The error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_uncompress/#bugs","title":"BUGS","text":"

The lack of single pass processing and the need to hold all data in memory as mentioned in CMS_verify() also applies to CMS_decompress().

"},{"location":"man3/CMS_uncompress/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_compress(3)

"},{"location":"man3/CMS_uncompress/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/CMS_verify/","title":"CMS_verify","text":""},{"location":"man3/CMS_verify/#name","title":"NAME","text":"

CMS_verify, CMS_SignedData_verify, CMS_get0_signers - verify a CMS SignedData structure

"},{"location":"man3/CMS_verify/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store,\n               BIO *detached_data, BIO *out, unsigned int flags);\nBIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data,\n                           STACK_OF(X509) *scerts, X509_STORE *store,\n                           STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls,\n                           unsigned int flags,\n                           OSSL_LIB_CTX *libctx, const char *propq);\n\nSTACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_verify/#description","title":"DESCRIPTION","text":"

CMS_verify() is very similar to PKCS7_verify(3). It verifies a CMS SignedData structure contained in a structure of type CMS_ContentInfo. cms points to the CMS_ContentInfo structure to verify. The optional certs parameter refers to a set of certificates in which to search for signing certificates. It is also used as a source of untrusted intermediate CA certificates for chain building. cms may contain extra untrusted CA certificates that may be used for chain building as well as CRLs that may be used for certificate validation. store may be NULL or point to the trusted certificate store to use for chain verification. detached_data refers to the signed data if the content is detached from cms. Otherwise detached_data should be NULL and the signed data must be in cms. The content is written to the BIO out unless it is NULL. flags is an optional set of flags, which can be used to modify the operation.

CMS_SignedData_verify() is like CMS_verify() except that it operates on CMS SignedData input in the sd argument, it has some additional parameters described next, and on success it returns the verified content as a memory BIO. The optional extra parameter may be used to provide untrusted CA certificates that may be helpful for chain building in certificate validation. This list of certificates must not contain duplicates. The optional crls parameter may be used to provide extra CRLs. Also the list of CRLs must not contain duplicates. The optional parameters library context libctx and property query propq are used when retrieving algorithms from providers.

CMS_get0_signers() retrieves the signing certificate(s) from cms; it may only be called after a successful CMS_verify() or CMS_SignedData_verify() operation.

"},{"location":"man3/CMS_verify/#verify-process","title":"VERIFY PROCESS","text":"

Normally the verify process proceeds as follows.

Initially some sanity checks are performed on cms. The type of cms must be SignedData. There must be at least one signature on the data and if the content is detached detached_data cannot be NULL.

An attempt is made to locate all the signing certificate(s), first looking in the certs parameter (if it is not NULL) and then looking in any certificates contained in the cms structure unless CMS_NOINTERN is set. If any signing certificate cannot be located the operation fails.

Each signing certificate is chain verified using the smimesign purpose and using the trusted certificate store store if supplied. Any internal certificates in the message, which may have been added using CMS_add1_cert(3), are used as untrusted CAs. If CRL checking is enabled in store and CMS_NOCRL is not set, any internal CRLs, which may have been added using CMS_add1_crl(3), are used in addition to attempting to look them up in store. If store is not NULL and any chain verify fails an error code is returned.

Finally the signed content is read (and written to out unless it is NULL) and the signature is checked.

If all signatures verify correctly then the function is successful.

Any of the following flags (ored together) can be passed in the flags parameter to change the default verify behaviour.

If CMS_NOINTERN is set the certificates in the message itself are not searched when locating the signing certificate(s). This means that all the signing certificates must be in the certs parameter.

If CMS_NOCRL is set and CRL checking is enabled in store then any CRLs in the message itself and provided via the crls parameter are ignored.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

If CMS_NO_SIGNER_CERT_VERIFY is set the signing certificates are not chain verified, unless CMS_CADES flag is also set.

If CMS_NO_ATTR_VERIFY is set the signed attributes signature is not verified, unless CMS_CADES flag is also set.

If CMS_CADES is set, each signer certificate is checked against the ESS signingCertificate or ESS signingCertificateV2 extension that is required in the signed attributes of the signature.

If CMS_NO_CONTENT_VERIFY is set then the content digest is not checked.

"},{"location":"man3/CMS_verify/#notes","title":"NOTES","text":"

One application of CMS_NOINTERN is to only accept messages signed by a small number of certificates. The acceptable certificates would be passed in the certs parameter. In this case if the signer certificate is not one of the certificates supplied in certs then the verify will fail because the signer cannot be found.

In some cases the standard techniques for looking up and validating certificates are not appropriate: for example an application may wish to lookup certificates in a database or perform customised verification. This can be achieved by setting and verifying the signer certificates manually using the signed data utility functions.

Care should be taken when modifying the default verify behaviour, for example setting CMS_NO_CONTENT_VERIFY will totally disable all content verification and any modified content will be considered valid. This combination is however useful if one merely wishes to write the content to out and its validity is not considered important.

Chain verification should arguably be performed using the signing time rather than the current time. However, since the signing time is supplied by the signer it cannot be trusted without additional evidence (such as a trusted timestamp).

"},{"location":"man3/CMS_verify/#return-values","title":"RETURN VALUES","text":"

CMS_verify() returns 1 for a successful verification and 0 if an error occurred.

CMS_SignedData_verify() returns a memory BIO containing the verified content, or NULL on error.

CMS_get0_signers() returns all signers or NULL if an error occurred.

The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_verify/#bugs","title":"BUGS","text":"

The trusted certificate store is not searched for the signing certificate. This is primarily due to the inadequacies of the current X509_STORE functionality.

The lack of single pass processing means that the signed content must all be held in memory if it is not detached.

"},{"location":"man3/CMS_verify/#see-also","title":"SEE ALSO","text":"

PKCS7_verify(3), CMS_add1_cert(3), CMS_add1_crl(3), OSSL_ESS_check_signing_certs(3), ERR_get_error(3), CMS_sign(3)

"},{"location":"man3/CMS_verify/#history","title":"HISTORY","text":"

CMS_SignedData_verify() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_verify/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2024 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.

"},{"location":"man3/CMS_verify_receipt/","title":"CMS_verify_receipt","text":""},{"location":"man3/CMS_verify_receipt/#name","title":"NAME","text":"

CMS_verify_receipt - verify a CMS signed receipt

"},{"location":"man3/CMS_verify_receipt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms,\n                       STACK_OF(X509) *certs, X509_STORE *store,\n                       unsigned int flags);\n
"},{"location":"man3/CMS_verify_receipt/#description","title":"DESCRIPTION","text":"

CMS_verify_receipt() verifies a CMS signed receipt. rcms is the signed receipt to verify. ocms is the original SignedData structure containing the receipt request. certs is a set of certificates in which to search for the signing certificate. store is a trusted certificate store (used for chain verification).

flags is an optional set of flags, which can be used to modify the verify operation.

"},{"location":"man3/CMS_verify_receipt/#notes","title":"NOTES","text":"

This functions behaves in a similar way to CMS_verify() except the flag values CMS_DETACHED, CMS_BINARY, CMS_TEXT and CMS_STREAM are not supported since they do not make sense in the context of signed receipts.

"},{"location":"man3/CMS_verify_receipt/#return-values","title":"RETURN VALUES","text":"

CMS_verify_receipt() returns 1 for a successful verification and zero if an error occurred.

The error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_verify_receipt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign_receipt(3), CMS_verify(3),

"},{"location":"man3/CMS_verify_receipt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 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.

"},{"location":"man3/COMP_CTX_new/","title":"COMP_CTX_new","text":""},{"location":"man3/COMP_CTX_new/#name","title":"NAME","text":"

COMP_CTX_new, COMP_CTX_get_method, COMP_CTX_get_type, COMP_get_type, COMP_get_name, COMP_CTX_free, COMP_compress_block, COMP_expand_block, COMP_zlib, COMP_zlib_oneshot, COMP_brotli, COMP_brotli_oneshot, COMP_zstd, COMP_zstd_oneshot, BIO_f_zlib, BIO_f_brotli, BIO_f_zstd - Compression support

"},{"location":"man3/COMP_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/comp.h>\n\nCOMP_CTX *COMP_CTX_new(COMP_METHOD *meth);\nvoid COMP_CTX_free(COMP_CTX *ctx);\nconst COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx);\nint COMP_CTX_get_type(const COMP_CTX* comp);\nint COMP_get_type(const COMP_METHOD *meth);\nconst char *COMP_get_name(const COMP_METHOD *meth);\n\nint COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen,\n                        unsigned char *in, int ilen);\nint COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen,\n                      unsigned char *in, int ilen);\n\nCOMP_METHOD *COMP_zlib(void);\nCOMP_METHOD *COMP_zlib_oneshot(void);\nCOMP_METHOD *COMP_brotli(void);\nCOMP_METHOD *COMP_brotli_oneshot(void);\nCOMP_METHOD *COMP_zstd(void);\nCOMP_METHOD *COMP_zstd_oneshot(void);\n\nconst BIO_METHOD *BIO_f_zlib(void);\nconst BIO_METHOD *BIO_f_brotli(void);\nconst BIO_METHOD *BIO_f_zstd(void);\n
"},{"location":"man3/COMP_CTX_new/#description","title":"DESCRIPTION","text":"

These functions provide compression support for OpenSSL. Compression is used within the OpenSSL library to support TLS record and certificate compression.

COMP_CTX_new() is used to create a new COMP_CTX structure used to compress data.

COMP_CTX_free() is used to free the returned COMP_CTX. If the argument is NULL, nothing is done.

COMP_CTX_get_method() returns the COMP_METHOD of the given ctx.

COMP_CTX_get_type() and COMP_get_type() return the NID for the COMP_CTX and COMP_METHOD, respectively. COMP_get_name() returns the name of the algorithm of the given COMP_METHOD.

COMP_compress_block() compresses b<ilen> bytes from the buffer in into the buffer b<out> of size olen using the algorithm specified by ctx.

COMP_expand_block() expands ilen bytes from the buffer in into the buffer out of size olen using the algorithm specified by ctx.

Methods (COMP_METHOD) may be specified by one of these functions. These functions will be available even if their corresponding compression algorithm is not configured into the OpenSSL library. In such a case, NULL will be returned.

BIO_f_zlib(), BIO_f_brotli() BIO_f_zstd() each return a BIO_METHOD that may be used to create a BIO via BIO_new(3) to read and write compressed files or streams. The functions are only available if the corresponding algorithm is compiled into the OpenSSL library. NULL may be returned if the algorithm fails to load dynamically.

"},{"location":"man3/COMP_CTX_new/#notes","title":"NOTES","text":"

While compressing non-compressible data, the output may be larger than the input. Care should be taken to size output buffers appropriate for both compression and expansion.

Compression support and compression algorithms must be enabled and built into the library before use. Refer to the INSTALL.md file when configuring OpenSSL.

ZLIB may be found at https://zlib.net

Brotli may be found at https://github.com/google/brotli.

Zstandard may be found at https://github.com/facebook/zstd.

Compression of SSL/TLS records is not recommended, as it has been shown to lead to the CRIME attack https://en.wikipedia.org/wiki/CRIME. It is disabled by default, and may be enabled by clearing the SSL_OP_NO_COMPRESSION option and setting the security level as appropriate. See the documentation for the SSL_CTX_set_options(3) and SSL_set_options(3) functions.

Compression is also used to support certificate compression as described in RFC8879 https://datatracker.ietf.org/doc/html/rfc8879. It may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and SSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the SSL_CTX_set_options(3) or SSL_set_options(3) functions.

COMP_zlib(), COMP_brotli() and COMP_zstd() are stream-based compression methods. Internal state (including compression dictionary) is maintained between calls. If an error is returned, the stream is corrupted, and should be closed.

COMP_zlib_oneshot(), COMP_brotli_oneshot() and COMP_zstd_oneshot() are not stream-based. These methods do not maintain state between calls. An error in one call does not affect future calls.

"},{"location":"man3/COMP_CTX_new/#return-values","title":"RETURN VALUES","text":"

COMP_CTX_new() returns a COMP_CTX on success, or NULL on failure.

COMP_CTX_get_method(), COMP_zlib(), COMP_zlib_oneshot(), COMP_brotli(), COMP_brotli_oneshot(), COMP_zstd(), and COMP_zstd_oneshot() return a COMP_METHOD on success, or NULL on failure.

COMP_CTX_get_type() and COMP_get_type() return a NID value. On failure, NID_undef is returned.

COMP_compress_block() and COMP_expand_block() return the number of bytes stored in the output buffer out. This may be 0. On failure, -1 is returned.

COMP_get_name() returns a const char * that must not be freed on success, or NULL on failure.

BIO_f_zlib(), BIO_f_brotli() and BIO_f_zstd() return NULL on error, and a BIO_METHOD on success.

"},{"location":"man3/COMP_CTX_new/#see-also","title":"SEE ALSO","text":"

BIO_new(3), SSL_CTX_set_options(3), SSL_set_options(3)

"},{"location":"man3/COMP_CTX_new/#history","title":"HISTORY","text":"

Brotli and Zstandard functions were added in OpenSSL 3.2.

"},{"location":"man3/COMP_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2024 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.

"},{"location":"man3/CONF_modules_free/","title":"CONF_modules_free","text":""},{"location":"man3/CONF_modules_free/#name","title":"NAME","text":"

CONF_modules_free, CONF_modules_finish, CONF_modules_unload - OpenSSL configuration cleanup functions

"},{"location":"man3/CONF_modules_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\nvoid CONF_modules_finish(void);\nvoid CONF_modules_unload(int all);\n

The following functions have been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void CONF_modules_free(void);\n
"},{"location":"man3/CONF_modules_free/#description","title":"DESCRIPTION","text":"

CONF_modules_free() closes down and frees up all memory allocated by all configuration modules. Normally, in versions of OpenSSL prior to 1.1.0, applications called CONF_modules_free() at exit to tidy up any configuration performed.

CONF_modules_finish() calls each configuration modules finish handler to free up any configuration that module may have performed.

CONF_modules_unload() finishes and unloads configuration modules. If all is set to 0 only modules loaded from DSOs will be unloads. If all is 1 all modules, including built-in modules will be unloaded.

"},{"location":"man3/CONF_modules_free/#return-values","title":"RETURN VALUES","text":"

None of the functions return a value.

"},{"location":"man3/CONF_modules_free/#see-also","title":"SEE ALSO","text":"

config(5), OPENSSL_config(3), CONF_modules_load_file_ex(3)

"},{"location":"man3/CONF_modules_free/#history","title":"HISTORY","text":"

CONF_modules_free() was deprecated in OpenSSL 1.1.0; do not use it. For more information see OPENSSL_init_crypto(3).

"},{"location":"man3/CONF_modules_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/CONF_modules_load_file/","title":"CONF_modules_load_file","text":""},{"location":"man3/CONF_modules_load_file/#name","title":"NAME","text":"

CONF_get1_default_config_file, CONF_modules_load_file_ex, CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions

"},{"location":"man3/CONF_modules_load_file/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\nchar *CONF_get1_default_config_file(void);\nint CONF_modules_load_file_ex(OSSL_LIB_CTX *libctx, const char *filename,\n                              const char *appname, unsigned long flags);\nint CONF_modules_load_file(const char *filename, const char *appname,\n                           unsigned long flags);\nint CONF_modules_load(const CONF *cnf, const char *appname,\n                      unsigned long flags);\n
"},{"location":"man3/CONF_modules_load_file/#description","title":"DESCRIPTION","text":"

The function CONF_get1_default_config_file() determines the default configuration file pathname as follows. If the OPENSSL_CONF environment variable is set its value is returned. Else the function returns the path obtained using X509_get_default_cert_area(3) with the filename \"openssl.cnf\" appended. The caller is responsible for freeing any string returned.

The function CONF_modules_load_file_ex() configures OpenSSL using library context libctx file filename and application name appname. If filename is NULL the standard OpenSSL configuration file is used as determined by calling CONF_get1_default_config_file(). If appname is NULL the standard OpenSSL application name openssl_conf is used. The behaviour can be customized using flags. Note that, the error suppressing can be overridden by config_diagnostics as described in config(5).

CONF_modules_load_file() is the same as CONF_modules_load_file_ex() but has a NULL library context.

CONF_modules_load() is identical to CONF_modules_load_file() except it reads configuration information from cnf.

"},{"location":"man3/CONF_modules_load_file/#notes","title":"NOTES","text":"

The following flags are currently recognized:

If CONF_MFLAGS_IGNORE_ERRORS is set errors returned by individual configuration modules are ignored. If not set the first module error is considered fatal and no further modules are loaded.

Normally any modules errors will add error information to the error queue. If CONF_MFLAGS_SILENT is set no error information is added.

If CONF_MFLAGS_IGNORE_RETURN_CODES is set the function unconditionally returns success. This is used by default in OPENSSL_init_crypto(3) to ignore any errors in the default system-wide configuration file, as having all OpenSSL applications fail to start when there are potentially minor issues in the file is too risky. Applications calling CONF_modules_load_file_ex explicitly should not generally set this flag.

If CONF_MFLAGS_NO_DSO is set configuration module loading from DSOs is disabled.

CONF_MFLAGS_IGNORE_MISSING_FILE if set will make CONF_load_modules_file() ignore missing configuration files. Normally a missing configuration file return an error.

CONF_MFLAGS_DEFAULT_SECTION if set and appname is not NULL will use the default section pointed to by openssl_conf if appname does not exist.

By using CONF_modules_load_file_ex() with appropriate flags an application can customise application configuration to best suit its needs. In some cases the use of a configuration file is optional and its absence is not an error: in this case CONF_MFLAGS_IGNORE_MISSING_FILE would be set.

Errors during configuration may also be handled differently by different applications. For example in some cases an error may simply print out a warning message and the application continue. In other cases an application might consider a configuration file error as fatal and exit immediately.

Applications can use the CONF_modules_load() function if they wish to load a configuration file themselves and have finer control over how errors are treated.

"},{"location":"man3/CONF_modules_load_file/#return-values","title":"RETURN VALUES","text":"

These functions return 1 for success and a zero or negative value for failure. If module errors are not ignored the return code will reflect the return value of the failing module (this will always be zero or negative).

"},{"location":"man3/CONF_modules_load_file/#examples","title":"EXAMPLES","text":"

Load a configuration file and print out any errors and exit (missing file considered fatal):

if (CONF_modules_load_file_ex(libctx, NULL, NULL, 0) <= 0) {\n    fprintf(stderr, \"FATAL: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

Load default configuration file using the section indicated by \"myapp\", tolerate missing files, but exit on other errors:

if (CONF_modules_load_file_ex(NULL, NULL, \"myapp\",\n                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {\n    fprintf(stderr, \"FATAL: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

Load custom configuration file and section, only print warnings on error, missing configuration file ignored:

if (CONF_modules_load_file_ex(NULL, \"/something/app.cnf\", \"myapp\",\n                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {\n    fprintf(stderr, \"WARNING: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n}\n

Load and parse configuration file manually, custom error handling:

FILE *fp;\nCONF *cnf = NULL;\nlong eline;\n\nfp = fopen(\"/somepath/app.cnf\", \"r\");\nif (fp == NULL) {\n    fprintf(stderr, \"Error opening configuration file\\n\");\n    /* Other missing configuration file behaviour */\n} else {\n    cnf = NCONF_new_ex(libctx, NULL);\n    if (NCONF_load_fp(cnf, fp, &eline) == 0) {\n        fprintf(stderr, \"Error on line %ld of configuration file\\n\", eline);\n        ERR_print_errors_fp(stderr);\n        /* Other malformed configuration file behaviour */\n    } else if (CONF_modules_load(cnf, \"appname\", 0) <= 0) {\n        fprintf(stderr, \"Error configuring application\\n\");\n        ERR_print_errors_fp(stderr);\n        /* Other configuration error behaviour */\n    }\n    fclose(fp);\n    NCONF_free(cnf);\n}\n
"},{"location":"man3/CONF_modules_load_file/#see-also","title":"SEE ALSO","text":"

config(5), OPENSSL_config(3), NCONF_new_ex(3)

"},{"location":"man3/CONF_modules_load_file/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2022 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.

"},{"location":"man3/CRYPTO_THREAD_run_once/","title":"CRYPTO_THREAD_run_once","text":""},{"location":"man3/CRYPTO_THREAD_run_once/#name","title":"NAME","text":"

CRYPTO_THREAD_run_once, CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or, CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int, OSSL_set_max_threads, OSSL_get_max_threads, OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL, OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support

"},{"location":"man3/CRYPTO_THREAD_run_once/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nCRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;\nint CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));\n\nCRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);\nint CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);\nint CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);\nint CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);\nvoid CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);\n\nint CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_add64(uint64_t *val, uint64_t op, uint64_t *ret,\n                        CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_and(uint64_t *val, uint64_t op, uint64_t *ret,\n                      CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,\n                     CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);\n\nint OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);\nuint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);\nuint32_t OSSL_get_thread_support_flags(void);\n\n#define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL\n#define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN\n
"},{"location":"man3/CRYPTO_THREAD_run_once/#description","title":"DESCRIPTION","text":"

OpenSSL can be safely used in multi-threaded applications provided that support for the underlying OS threading API is built-in. Currently, OpenSSL supports the pthread and Windows APIs. OpenSSL can also be built without any multi-threading support, for example on platforms that don't provide any threading support or that provide a threading API that is not yet supported by OpenSSL.

The following multi-threading function are provided:

"},{"location":"man3/CRYPTO_THREAD_run_once/#return-values","title":"RETURN VALUES","text":"

CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.

CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.

CRYPTO_THREAD_lock_free() returns no value.

OSSL_set_max_threads() returns 1 on success and 0 on failure. Returns failure if OpenSSL-managed thread pooling is not supported (for example, if it is not supported on the current platform, or because OpenSSL is not built with the necessary support).

OSSL_get_max_threads() returns the maximum number of threads currently allowed to be used by the thread pool. If thread pooling is disabled or not available, returns 0.

OSSL_get_thread_support_flags() returns zero or more OSSL_THREAD_SUPPORT_FLAG values.

The other functions return 1 on success, or 0 on error.

"},{"location":"man3/CRYPTO_THREAD_run_once/#notes","title":"NOTES","text":"

On Windows platforms the CRYPTO_THREAD_* types and functions in the <openssl/crypto.h> header are dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/crypto.h> where use of CRYPTO_THREAD_* types and functions is required.

"},{"location":"man3/CRYPTO_THREAD_run_once/#examples","title":"EXAMPLES","text":"

You can find out if OpenSSL was configured with thread support:

#include <openssl/opensslconf.h>\n#if defined(OPENSSL_THREADS)\n    /* thread support enabled */\n#else\n    /* no thread support */\n#endif\n

This example safely initializes and uses a lock.

#ifdef _WIN32\n

# # include #endif #include 

static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;\nstatic CRYPTO_RWLOCK *lock;\n\nstatic void myinit(void)\n{\n    lock = CRYPTO_THREAD_lock_new();\n}\n\nstatic int mylock(void)\n{\n    if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)\n        return 0;\n    return CRYPTO_THREAD_write_lock(lock);\n}\n\nstatic int myunlock(void)\n{\n    return CRYPTO_THREAD_unlock(lock);\n}\n\nint serialized(void)\n{\n    int ret = 0;\n\n    if (!mylock()) {\n       /* Do not unlock unless the lock was successfully acquired. */\n       return 0;\n    }\n\n    /* Your code here, do not return without releasing the lock! */\n    ret = ... ;\n    myunlock();\n    return ret;\n}\n

Finalization of locks is an advanced topic, not covered in this example. This can only be done at process exit or when a dynamically loaded library is no longer in use and is unloaded. The simplest solution is to just \"leak\" the lock in applications and not repeatedly load/unload shared libraries that allocate locks.

"},{"location":"man3/CRYPTO_THREAD_run_once/#see-also","title":"SEE ALSO","text":"

crypto(7), openssl-threads(7).

"},{"location":"man3/CRYPTO_THREAD_run_once/#history","title":"HISTORY","text":"

CRYPTO_atomic_store() was added in OpenSSL 3.4.0

"},{"location":"man3/CRYPTO_THREAD_run_once/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/CRYPTO_get_ex_new_index/","title":"CRYPTO_get_ex_new_index","text":""},{"location":"man3/CRYPTO_get_ex_new_index/#name","title":"NAME","text":"

CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data - functions supporting application-specific data

"},{"location":"man3/CRYPTO_get_ex_new_index/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint CRYPTO_get_ex_new_index(int class_index,\n                            long argl, void *argp,\n                            CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func,\n                            CRYPTO_EX_free *free_func);\n\ntypedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,\n                           int idx, long argl, void *argp);\ntypedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,\n                            int idx, long argl, void *argp);\ntypedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,\n                          void **from_d, int idx, long argl, void *argp);\n\nint CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad);\n\nint CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,\n                         int idx);\n\nint CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);\n\nvoid *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *r, int idx);\n\nvoid CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);\n\nint CRYPTO_free_ex_index(int class_index, int idx);\n
"},{"location":"man3/CRYPTO_get_ex_new_index/#description","title":"DESCRIPTION","text":"

Several OpenSSL structures can have application-specific data attached to them, known as \"exdata.\" The specific structures are:

BIO\nDH\nDSA\nEC_KEY\nENGINE\nEVP_PKEY\nRSA\nSSL\nSSL_CTX\nSSL_SESSION\nUI\nUI_METHOD\nX509\nX509_STORE\nX509_STORE_CTX\n

In addition, the APP name is reserved for use by application code.

Each is identified by an CRYPTO_EX_INDEX_xxx define in the header file <openssl/crypto.h>. In addition, CRYPTO_EX_INDEX_APP is reserved for applications to use this facility for their own structures.

The API described here is used by OpenSSL to manipulate exdata for specific structures. Since the application data can be anything at all it is passed and retrieved as a void * type.

The CRYPTO_EX_DATA type is opaque. To initialize the exdata part of a structure, call CRYPTO_new_ex_data(). This is only necessary for CRYPTO_EX_INDEX_APP objects.

Exdata types are identified by an index, an integer guaranteed to be unique within structures for the lifetime of the program. Applications using exdata typically call CRYPTO_get_ex_new_index at startup, and store the result in a global variable, or write a wrapper function to provide lazy evaluation. The class_index should be one of the CRYPTO_EX_INDEX_xxx values. The argl and argp parameters are saved to be passed to the callbacks but are otherwise not used. In order to transparently manipulate exdata, three callbacks must be provided. The semantics of those callbacks are described below.

When copying or releasing objects with exdata, the callback functions are called in increasing order of their index value.

If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() when this is done. This will replace the callbacks with no-ops so that applications don't crash. Any existing exdata will be leaked.

To set or get the exdata on an object, the appropriate type-specific routine must be used. This is because the containing structure is opaque and the CRYPTO_EX_DATA field is not accessible. In both API's, the idx parameter should be an already-created index value.

When setting exdata, the pointer specified with a particular index is saved, and returned on a subsequent \"get\" call. If the application is going to release the data, it must make sure to set a NULL value at the index, to avoid likely double-free crashes.

The function CRYPTO_free_ex_data is used to free all exdata attached to a structure. The appropriate type-specific routine must be used. The class_index identifies the structure type, the obj is a pointer to the actual structure, and r is a pointer to the structure's exdata field.

"},{"location":"man3/CRYPTO_get_ex_new_index/#callback-functions","title":"Callback Functions","text":"

This section describes how the callback functions are used. Applications that are defining their own exdata using CYPRTO_EX_INDEX_APP must call them as described here.

When a structure is initially allocated (such as RSA_new()) then the new_func() is called for every defined index. There is no requirement that the entire parent, or containing, structure has been set up. The new_func() is typically used only to allocate memory to store the exdata, and perhaps an \"initialized\" flag within that memory. The exdata value may be allocated later on with CRYPTO_alloc_ex_data(), or may be set by calling CRYPTO_set_ex_data().

When a structure is free'd (such as SSL_CTX_free()) then the free_func() is called for every defined index. Again, the state of the parent structure is not guaranteed. The free_func() may be called with a NULL pointer.

Both new_func() and free_func() take the same parameters. The parent is the pointer to the structure that contains the exdata. The ptr is the current exdata item; for new_func() this will typically be NULL. The r parameter is a pointer to the exdata field of the object. The idx is the index and is the value returned when the callbacks were initially registered via CRYPTO_get_ex_new_index() and can be used if the same callback handles different types of exdata.

dup_func() is called when a structure is being copied. This is only done for SSL, SSL_SESSION, EC_KEY objects and BIO chains via BIO_dup_chain(). The to and from parameters are pointers to the destination and source CRYPTO_EX_DATA structures, respectively. The *from_d parameter is a pointer to the source exdata. When the dup_func() returns, the value in *from_d is copied to the destination ex_data. If the pointer contained in *pptr is not modified by the dup_func(), then both to and from will point to the same data. The idx, argl and argp parameters are as described for the other two callbacks. If the dup_func() returns 0 the whole CRYPTO_dup_ex_data() will fail.

"},{"location":"man3/CRYPTO_get_ex_new_index/#return-values","title":"RETURN VALUES","text":"

CRYPTO_get_ex_new_index() returns a new index or -1 on failure.

CRYPTO_free_ex_index(), CRYPTO_alloc_ex_data() and CRYPTO_set_ex_data() return 1 on success or 0 on failure.

CRYPTO_get_ex_data() returns the application data or NULL on failure; note that NULL may be a valid value.

dup_func() should return 0 for failure and 1 for success.

"},{"location":"man3/CRYPTO_get_ex_new_index/#history","title":"HISTORY","text":"

CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.

The signature of the dup_func() callback was changed in OpenSSL 3.0 to use the type void ** for from_d. Previously this parameter was of type void *.

Support for ENGINE \"exdata\" was deprecated in OpenSSL 3.0.

"},{"location":"man3/CRYPTO_get_ex_new_index/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 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.

"},{"location":"man3/CRYPTO_memcmp/","title":"CRYPTO_memcmp","text":""},{"location":"man3/CRYPTO_memcmp/#name","title":"NAME","text":"

CRYPTO_memcmp - Constant time memory comparison

"},{"location":"man3/CRYPTO_memcmp/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint CRYPTO_memcmp(const void *a, const void *b, size_t len);\n
"},{"location":"man3/CRYPTO_memcmp/#description","title":"DESCRIPTION","text":"

The CRYPTO_memcmp function compares the len bytes pointed to by a and b for equality. It takes an amount of time dependent on len, but independent of the contents of the memory regions pointed to by a and b.

"},{"location":"man3/CRYPTO_memcmp/#return-values","title":"RETURN VALUES","text":"

CRYPTO_memcmp() returns 0 if the memory regions are equal and nonzero otherwise.

"},{"location":"man3/CRYPTO_memcmp/#notes","title":"NOTES","text":"

Unlike memcmp(2), this function cannot be used to order the two memory regions as the return value when they differ is undefined, other than being nonzero.

"},{"location":"man3/CRYPTO_memcmp/#copyright","title":"COPYRIGHT","text":"

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.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/","title":"CTLOG_STORE_get0_log_by_id","text":""},{"location":"man3/CTLOG_STORE_get0_log_by_id/#name","title":"NAME","text":"

CTLOG_STORE_get0_log_by_id - Get a Certificate Transparency log from a CTLOG_STORE

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nconst CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,\n                                        const uint8_t *log_id,\n                                        size_t log_id_len);\n
"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#description","title":"DESCRIPTION","text":"

A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency (CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2). Therefore, it is useful to be able to look up more information about a log (e.g. its public key) using this LogID.

CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG in a CTLOG_STORE that has a given LogID.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#return-values","title":"RETURN VALUES","text":"

CTLOG_STORE_get0_log_by_id returns a CTLOG with the given LogID, if it exists in the given CTLOG_STORE, otherwise it returns NULL.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#see-also","title":"SEE ALSO","text":"

ct(7), CTLOG_STORE_new(3)

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#history","title":"HISTORY","text":"

The CTLOG_STORE_get0_log_by_id() function was added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/CTLOG_STORE_new/","title":"CTLOG_STORE_new","text":""},{"location":"man3/CTLOG_STORE_new/#name","title":"NAME","text":"

CTLOG_STORE_new_ex, CTLOG_STORE_new, CTLOG_STORE_free, CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - Create and populate a Certificate Transparency log list

"},{"location":"man3/CTLOG_STORE_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCTLOG_STORE *CTLOG_STORE_new_ex(OSSL_LIB_CTX *libctx, const char *propq);\nCTLOG_STORE *CTLOG_STORE_new(void);\nvoid CTLOG_STORE_free(CTLOG_STORE *store);\n\nint CTLOG_STORE_load_default_file(CTLOG_STORE *store);\nint CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);\n
"},{"location":"man3/CTLOG_STORE_new/#description","title":"DESCRIPTION","text":"

A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency logs). The list can be loaded from one or more files and then searched by LogID (see RFC 6962, Section 3.2, for the definition of a LogID).

CTLOG_STORE_new_ex() creates an empty list of CT logs associated with the library context libctx and the property query string propq.

CTLOG_STORE_new() does the same thing as CTLOG_STORE_new_ex() but with the default library context and property query string.

The CTLOG_STORE is then populated by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). CTLOG_STORE_load_default_file() loads from the default file, which is named ct_log_list.cnf in OPENSSLDIR (see the output of openssl-version(1)). This can be overridden using an environment variable named CTLOG_FILE. CTLOG_STORE_load_file() loads from a caller-specified file path instead. Both of these functions append any loaded CT logs to the CTLOG_STORE.

The expected format of the file is:

enabled_logs=foo,bar\n\n[foo]\ndescription = Log 1\nkey = <base64-encoded DER SubjectPublicKeyInfo here>\n\n[bar]\ndescription = Log 2\nkey = <base64-encoded DER SubjectPublicKeyInfo here>\n

Once a CTLOG_STORE is no longer required, it should be passed to CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along with the CTLOG_STORE itself. If the argument is NULL, nothing is done.

"},{"location":"man3/CTLOG_STORE_new/#notes","title":"NOTES","text":"

If there are any invalid CT logs in a file, they are skipped and the remaining valid logs will still be added to the CTLOG_STORE. A CT log will be considered invalid if it is missing a \"key\" or \"description\" field.

"},{"location":"man3/CTLOG_STORE_new/#return-values","title":"RETURN VALUES","text":"

Both CTLOG_STORE_load_default_file and CTLOG_STORE_load_file return 1 if all CT logs in the file are successfully parsed and loaded, 0 otherwise.

"},{"location":"man3/CTLOG_STORE_new/#see-also","title":"SEE ALSO","text":"

ct(7), CTLOG_STORE_get0_log_by_id(3), SSL_CTX_set_ctlog_list_file(3)

"},{"location":"man3/CTLOG_STORE_new/#history","title":"HISTORY","text":"

CTLOG_STORE_new_ex was added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_STORE_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/CTLOG_new/","title":"CTLOG_new","text":""},{"location":"man3/CTLOG_new/#name","title":"NAME","text":"

CTLOG_new_ex, CTLOG_new, CTLOG_new_from_base64, CTLOG_new_from_base64_ex, CTLOG_free, CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key - encapsulates information about a Certificate Transparency log

"},{"location":"man3/CTLOG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCTLOG *CTLOG_new_ex(EVP_PKEY *public_key, const char *name,\n                    OSSL_LIB_CTX *libctx, const char *propq);\nCTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);\n\nint CTLOG_new_from_base64_ex(CTLOG **ct_log, const char *pkey_base64,\n                             const char *name, OSSL_LIB_CTX *libctx,\n                             const char *propq);\nint CTLOG_new_from_base64(CTLOG ** ct_log,\n                          const char *pkey_base64, const char *name);\nvoid CTLOG_free(CTLOG *log);\nconst char *CTLOG_get0_name(const CTLOG *log);\nvoid CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,\n                       size_t *log_id_len);\nEVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);\n
"},{"location":"man3/CTLOG_new/#description","title":"DESCRIPTION","text":"

CTLOG_new_ex() returns a new CTLOG that represents the Certificate Transparency (CT) log with the given public key and associates it with the library context libctx and property query string propq. A name must also be provided that can be used to help users identify this log. Ownership of the public key is transferred.

CTLOG_new() does the same thing as CTLOG_new_ex() but with the default library context and the default property query string.

CTLOG_new_from_base64_ex() also creates a new CTLOG, but takes the public key in base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG. The base64 will be decoded and the public key parsed. The CTLOG will be associated with the given library context libctx and property query string propq.

CTLOG_new_from_base64() does the same thing as CTLOG_new_from_base64_ex() except that the default library context and property query string are used.

Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that was passed to it. If the argument to CTLOG_free() is NULL, nothing is done.

CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was created. Ownership of the string remains with the CTLOG.

CTLOG_get0_log_id() sets *log_id to point to a string containing that log's LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of the string remains with the CTLOG.

CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the EVP_PKEY remains with the CTLOG.

"},{"location":"man3/CTLOG_new/#return-values","title":"RETURN VALUES","text":"

CTLOG_new() will return NULL if an error occurs.

CTLOG_new_from_base64() will return 1 on success, 0 otherwise.

"},{"location":"man3/CTLOG_new/#see-also","title":"SEE ALSO","text":"

ct(7)

"},{"location":"man3/CTLOG_new/#history","title":"HISTORY","text":"

The functions CTLOG_new_ex() and CTLOG_new_from_base64_ex() were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/","title":"CT_POLICY_EVAL_CTX_new","text":""},{"location":"man3/CT_POLICY_EVAL_CTX_new/#name","title":"NAME","text":"

CT_POLICY_EVAL_CTX_new_ex, CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_ex(OSSL_LIB_CTX *libctx,\n                                              const char *propq);\nCT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);\nvoid CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);\nX509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);\nint CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);\nX509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);\nint CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);\nconst CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);\nvoid CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx,\n                                               CTLOG_STORE *log_store);\nuint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx);\nvoid CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms);\n
"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#description","title":"DESCRIPTION","text":"

A CT_POLICY_EVAL_CTX is used by functions that evaluate whether Signed Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. This policy may be, for example, that at least one valid SCT is available. To determine this, an SCT's timestamp and signature must be verified. This requires:

The above requirements are met using the setters described below.

CT_POLICY_EVAL_CTX_new_ex() creates an empty policy evaluation context and associates it with the given library context libctx and property query string propq.

CT_POLICY_EVAL_CTX_new() does the same thing as CT_POLICY_EVAL_CTX_new_ex() except that it uses the default library context and property query string.

The CT_POLICY_EVAL_CTX should then be populated using:

Each setter has a matching getter for accessing the current value.

When no longer required, the CT_POLICY_EVAL_CTX should be passed to CT_POLICY_EVAL_CTX_free() to delete it. If the argument to CT_POLICY_EVAL_CTX_free() is NULL, nothing is done.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#notes","title":"NOTES","text":"

The issuer certificate only needs to be provided if at least one of the SCTs was issued for a pre-certificate. This will be the case for SCTs embedded in a certificate (i.e. those in an X.509 extension), but may not be the case for SCTs found in the TLS SCT extension or OCSP response.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#return-values","title":"RETURN VALUES","text":"

CT_POLICY_EVAL_CTX_new_ex() and CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#see-also","title":"SEE ALSO","text":"

ct(7)

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#history","title":"HISTORY","text":"

CT_POLICY_EVAL_CTX_new_ex was added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/DEFINE_STACK_OF/","title":"DEFINE_STACK_OF","text":""},{"location":"man3/DEFINE_STACK_OF/#name","title":"NAME","text":"

DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, DEFINE_SPECIAL_STACK_OF_CONST, sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort, sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve, OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all, OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push, OPENSSL_sk_reserve, OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort, OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero - stack container

"},{"location":"man3/DEFINE_STACK_OF/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/safestack.h>\n\nSTACK_OF(TYPE)\nDEFINE_STACK_OF(TYPE)\nDEFINE_STACK_OF_CONST(TYPE)\nDEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)\nDEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)\n\ntypedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);\ntypedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);\ntypedef void (*sk_TYPE_freefunc)(TYPE *a);\n\nint sk_TYPE_num(const STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);\nSTACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);\nSTACK_OF(TYPE) *sk_TYPE_new_null(void);\nint sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n);\nvoid sk_TYPE_free(STACK_OF(TYPE) *sk);\nvoid sk_TYPE_zero(STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);\nTYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);\nint sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);\nTYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);\nvoid sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);\nint sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);\nTYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);\nint sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum);\nvoid sk_TYPE_sort(const STACK_OF(TYPE) *sk);\nint sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);\nSTACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);\nSTACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,\n                                  sk_TYPE_copyfunc copyfunc,\n                                  sk_TYPE_freefunc freefunc);\nsk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,\n                                        sk_TYPE_compfunc compare));\nSTACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n);\n
"},{"location":"man3/DEFINE_STACK_OF/#description","title":"DESCRIPTION","text":"

Applications can create and use their own stacks by placing any of the macros described below in a header file. These macros define typesafe inline functions that wrap around the utility OPENSSL_sk_ API. In the description here, TYPE is used as a placeholder for any of the OpenSSL datatypes, such as X509.

The STACK_OF() macro returns the name for a stack of the specified TYPE. This is an opaque pointer to a structure declaration. This can be used in every header file that references the stack. There are several DEFINE... macros that create static inline functions for all of the functions described on this page. This should normally be used in one source file, and the stack manipulation is wrapped with application-specific functions.

DEFINE_STACK_OF() creates set of functions for a stack of TYPE elements. The type is referenced by STACK_OF(TYPE) and each function name begins with sk_TYPE_. DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except each element is constant.

/* DEFINE_STACK_OF(TYPE) */\nTYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n/* DEFINE_STACK_OF_CONST(TYPE) */\nconst TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n

DEFINE_SPECIAL_STACK_OF() and DEFINE_SPECIAL_STACK_OF_CONST() are similar except FUNCNAME is used in the function names:

/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */\nTYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */\nconst TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n

sk_TYPE_num() returns the number of elements in sk or -1 if sk is NULL.

sk_TYPE_value() returns element idx in sk, where idx starts at zero. If idx is out of range then NULL is returned.

sk_TYPE_new() allocates a new empty stack using comparison function compare. If compare is NULL then no comparison function is used. This function is equivalent to sk_TYPE_new_reserve(compare, 0).

sk_TYPE_new_null() allocates a new empty stack with no comparison function. This function is equivalent to sk_TYPE_new_reserve(NULL, 0).

sk_TYPE_reserve() allocates additional memory in the sk structure such that the next n calls to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause memory to be allocated or reallocated. If n is zero, any excess space allocated in the sk structure is freed. On error sk is unchanged.

sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional memory allocated to hold n elements if n is positive. The next n calls to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause memory to be allocated or reallocated. If n is zero or less than zero, no memory is allocated. sk_TYPE_new_reserve() also sets the comparison function compare to the newly created stack. If compare is NULL then no comparison function is used.

sk_TYPE_set_cmp_func() sets the comparison function of sk to compare. The previous comparison function is returned or NULL if there was no previous comparison function.

sk_TYPE_free() frees up the sk structure. It does not free up any elements of sk. After this call sk is no longer valid.

sk_TYPE_zero() sets the number of elements in sk to zero. It does not free sk so after this call sk is still valid.

sk_TYPE_pop_free() frees up all elements of sk and sk itself. The free function freefunc() is called on each element to free it.

sk_TYPE_delete() deletes element i from sk. It returns the deleted element or NULL if i is out of range.

sk_TYPE_delete_ptr() deletes element matching ptr from sk. It returns the deleted element or NULL if no element matching ptr was found.

sk_TYPE_insert() inserts ptr into sk at position idx. Any existing elements at or after idx are moved downwards. If idx is out of range the new element is appended to sk. sk_TYPE_insert() either returns the number of elements in sk after the new element is inserted or zero if an error (such as memory allocation failure) occurred.

sk_TYPE_push() appends ptr to sk it is equivalent to:

sk_TYPE_insert(sk, ptr, -1);\n

sk_TYPE_unshift() inserts ptr at the start of sk it is equivalent to:

sk_TYPE_insert(sk, ptr, 0);\n

sk_TYPE_pop() returns and removes the last element from sk.

sk_TYPE_shift() returns and removes the first element from sk.

sk_TYPE_set() sets element idx of sk to ptr replacing the current element. The new element value is returned or NULL if an error occurred: this will only happen if sk is NULL or idx is out of range.

sk_TYPE_find() searches sk for the element ptr. In the case where no comparison function has been specified, the function performs a linear search for a pointer equal to ptr. The index of the first matching element is returned or -1 if there is no match. In the case where a comparison function has been specified, sk is sorted and sk_TYPE_find() returns the index of a matching element or -1 if there is no match. Note that, in this case the comparison function will usually compare the values pointed to rather than the pointers themselves and the order of elements in sk can change.

sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison function has been specified and no matching element is found. Instead of returning -1, sk_TYPE_find_ex() returns the index of the element either before or after the location where ptr would be if it were present in sk. The function also does not guarantee that the first matching element in the sorted stack is returned.

sk_TYPE_find_all() operates like sk_TYPE_find() but it also sets the *pnum to number of matching elements in the stack. In case no comparison function has been specified the *pnum will be always set to 1 if matching element was found, 0 otherwise.

sk_TYPE_sort() sorts sk using the supplied comparison function.

sk_TYPE_is_sorted() returns 1 if sk is sorted and 0 otherwise.

sk_TYPE_dup() returns a shallow copy of sk or an empty stack if the passed stack is NULL. Note the pointers in the copy are identical to the original.

sk_TYPE_deep_copy() returns a new stack where each element has been copied or an empty stack if the passed stack is NULL. Copying is performed by the supplied copyfunc() and freeing by freefunc(). The function freefunc() is only called if an error occurs.

"},{"location":"man3/DEFINE_STACK_OF/#notes","title":"NOTES","text":"

Care should be taken when accessing stacks in multi-threaded environments. Any operation which increases the size of a stack such as sk_TYPE_insert() or sk_TYPE_push() can \"grow\" the size of an internal array and cause race conditions if the same stack is accessed in a different thread. Operations such as sk_TYPE_find() and sk_TYPE_sort() can also reorder the stack.

Any comparison function supplied should use a metric suitable for use in a binary search operation. That is it should return zero, a positive or negative value if a is equal to, greater than or less than b respectively.

Care should be taken when checking the return values of the functions sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the matching element. In particular 0 indicates a matching first element. A failed search is indicated by a -1 return value.

STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and DEFINE_SPECIAL_STACK_OF() are implemented as macros.

It is not an error to call sk_TYPE_num(), sk_TYPE_value(), sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free(), sk_TYPE_delete(), sk_TYPE_delete_ptr(), sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_find(), sk_TYPE_find_ex(), and sk_TYPE_find_all() on a NULL stack, empty stack, or with an invalid index. An error is not raised in these conditions.

The underlying utility OPENSSL_sk_ API should not be used directly. It defines these functions: OPENSSL_sk_deep_copy(), OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(), OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_find_all(), OPENSSL_sk_free(), OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(), OPENSSL_sk_new_null(), OPENSSL_sk_new_reserve(), OPENSSL_sk_num(), OPENSSL_sk_pop(), OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(), OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(), OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(), OPENSSL_sk_zero().

"},{"location":"man3/DEFINE_STACK_OF/#return-values","title":"RETURN VALUES","text":"

sk_TYPE_num() returns the number of elements in the stack or -1 if the passed stack is NULL.

sk_TYPE_value() returns a pointer to a stack element or NULL if the index is out of range.

sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty stack or NULL if an error occurs.

sk_TYPE_reserve() returns 1 on successful allocation of the required memory or 0 on error.

sk_TYPE_set_cmp_func() returns the old comparison function or NULL if there was no old comparison function.

sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do not return values.

sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr() return a pointer to the deleted element or NULL on error.

sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total number of elements in the stack and 0 if an error occurred.

sk_TYPE_set() returns a pointer to the replacement element or NULL on error.

sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element or -1 on error.

sk_TYPE_is_sorted() returns 1 if the stack is sorted and 0 if it is not.

sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the stack or NULL on error.

"},{"location":"man3/DEFINE_STACK_OF/#history","title":"HISTORY","text":"

Before OpenSSL 1.1.0, this was implemented via macros and not inline functions and was not a public API.

sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.

From OpenSSL 3.2.0, the sk_TYPE_find(), sk_TYPE_find_ex() and sk_TYPE_find_all() calls are read-only and do not sort the stack. To avoid any performance implications this change introduces, sk_TYPE_sort() should be called before these find operations.

Before OpenSSL 3.3.0 sk_TYPE_push() returned -1 if sk was NULL. It was changed to return 0 in this condition as for other errors.

"},{"location":"man3/DEFINE_STACK_OF/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/DES_random_key/","title":"DES_random_key","text":""},{"location":"man3/DES_random_key/#name","title":"NAME","text":"

DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, DES_fcrypt, DES_crypt - DES encryption

"},{"location":"man3/DES_random_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/des.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DES_random_key(DES_cblock *ret);\n\nint DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);\nint DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);\nint DES_set_key_checked(const_DES_cblock *key, DES_key_schedule *schedule);\nvoid DES_set_key_unchecked(const_DES_cblock *key, DES_key_schedule *schedule);\n\nvoid DES_set_odd_parity(DES_cblock *key);\nint DES_is_weak_key(const_DES_cblock *key);\n\nvoid DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,\n                     DES_key_schedule *ks, int enc);\nvoid DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,\n                      DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);\nvoid DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,\n                      DES_key_schedule *ks1, DES_key_schedule *ks2,\n                      DES_key_schedule *ks3, int enc);\n\nvoid DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      int enc);\nvoid DES_cfb_encrypt(const unsigned char *in, unsigned char *out,\n                     int numbits, long length, DES_key_schedule *schedule,\n                     DES_cblock *ivec, int enc);\nvoid DES_ofb_encrypt(const unsigned char *in, unsigned char *out,\n                     int numbits, long length, DES_key_schedule *schedule,\n                     DES_cblock *ivec);\nvoid DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      int enc);\nvoid DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                       long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                       int *num, int enc);\nvoid DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                       long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                       int *num);\n\nvoid DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      const_DES_cblock *inw, const_DES_cblock *outw, int enc);\n\nvoid DES_ede2_cbc_encrypt(const unsigned char *input, unsigned char *output,\n                          long length, DES_key_schedule *ks1,\n                          DES_key_schedule *ks2, DES_cblock *ivec, int enc);\nvoid DES_ede2_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_cblock *ivec,\n                            int *num, int enc);\nvoid DES_ede2_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_cblock *ivec, int *num);\n\nvoid DES_ede3_cbc_encrypt(const unsigned char *input, unsigned char *output,\n                          long length, DES_key_schedule *ks1,\n                          DES_key_schedule *ks2, DES_key_schedule *ks3,\n                          DES_cblock *ivec, int enc);\nvoid DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_key_schedule *ks3,\n                            DES_cblock *ivec, int *num, int enc);\nvoid DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_key_schedule *ks3,\n                            DES_cblock *ivec, int *num);\n\nDES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,\n                       long length, DES_key_schedule *schedule,\n                       const_DES_cblock *ivec);\nDES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],\n                        long length, int out_count, DES_cblock *seed);\nvoid DES_string_to_key(const char *str, DES_cblock *key);\nvoid DES_string_to_2keys(const char *str, DES_cblock *key1, DES_cblock *key2);\n\nchar *DES_fcrypt(const char *buf, const char *salt, char *ret);\nchar *DES_crypt(const char *buf, const char *salt);\n
"},{"location":"man3/DES_random_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3) and EVP_EncryptFinal_ex(3) or the equivalently named decrypt functions.

This library contains a fast implementation of the DES encryption algorithm.

There are two phases to the use of DES encryption. The first is the generation of a DES_key_schedule from a key, the second is the actual encryption. A DES key is of type DES_cblock. This type consists of 8 bytes with odd parity. The least significant bit in each byte is the parity bit. The key schedule is an expanded form of the key; it is used to speed the encryption process.

DES_random_key() generates a random key. The random generator must be seeded when calling this function. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail. If the function fails, 0 is returned.

Before a DES key can be used, it must be converted into the architecture dependent DES_key_schedule via the DES_set_key_checked() or DES_set_key_unchecked() function.

DES_set_key_checked() will check that the key passed is of odd parity and is not a weak or semi-weak key. If the parity is wrong, then -1 is returned. If the key is a weak key, then -2 is returned. If an error is returned, the key schedule is not generated.

DES_set_key() works like DES_set_key_checked() and remains for backward compatibility.

DES_set_odd_parity() sets the parity of the passed key to odd.

DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it is ok.

The following routines mostly operate on an input and output stream of _DES_cblock_s.

DES_ecb_encrypt() is the basic DES encryption routine that encrypts or decrypts a single 8-byte DES_cblock in electronic code book (ECB) mode. It always transforms the input data, pointed to by input, into the output data, pointed to by the output argument. If the encrypt argument is nonzero (DES_ENCRYPT), the input (cleartext) is encrypted in to the output (ciphertext) using the key_schedule specified by the schedule argument, previously set via DES_set_key. If encrypt is zero (DES_DECRYPT), the input (now ciphertext) is decrypted into the output (now cleartext). Input and output may overlap. DES_ecb_encrypt() does not return a value.

DES_ecb3_encrypt() encrypts/decrypts the input block by using three-key Triple-DES encryption in ECB mode. This involves encrypting the input with ks1, decrypting with the key schedule ks2, and then encrypting with ks3. This routine greatly reduces the chances of brute force breaking of DES and has the advantage of if ks1, ks2 and ks3 are the same, it is equivalent to just encryption using ECB mode and ks1 as the key.

The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES encryption by using ks1 for the final encryption.

DES_ncbc_encrypt() encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES. If the encrypt argument is nonzero, the routine cipher-block-chain encrypts the cleartext data pointed to by the input argument into the ciphertext pointed to by the output argument, using the key schedule provided by the schedule argument, and initialization vector provided by the ivec argument. If the length argument is not an integral multiple of eight bytes, the last block is copied to a temporary area and zero filled. The output is always an integral multiple of eight bytes.

DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses inw and outw to 'whiten' the encryption. inw and outw are secret (unlike the iv) and are as such, part of the key. So the key is sort of 24 bytes. This is much better than CBC DES.

DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with three keys. This means that each DES operation inside the CBC mode is C=E(ks3,D(ks2,E(ks1,M))). This mode is used by SSL.

The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by reusing ks1 for the final encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of Triple-DES is used by the RSAREF library.

DES_pcbc_encrypt() encrypts/decrypts using the propagating cipher block chaining mode used by Kerberos v4. Its parameters are the same as DES_ncbc_encrypt().

DES_cfb_encrypt() encrypts/decrypts using cipher feedback mode. This method takes an array of characters as input and outputs an array of characters. It does not require any padding to 8 character groups. Note: the ivec variable is changed and the new changed value needs to be passed to the next call to this function. Since this function runs a complete DES ECB encryption per numbits, this function is only suggested for use when sending a small number of characters.

DES_cfb64_encrypt() implements CFB mode of DES with 64-bit feedback. Why is this useful you ask? Because this routine will allow you to encrypt an arbitrary number of bytes, without 8 byte padding. Each call to this routine will encrypt the input bytes to output and then update ivec and num. num contains 'how far' we are though ivec. If this does not make much sense, read more about CFB mode of DES.

DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as DES_cfb64_encrypt() except that Triple-DES is used.

DES_ofb_encrypt() encrypts using output feedback mode. This method takes an array of characters as input and outputs an array of characters. It does not require any padding to 8 character groups. Note: the ivec variable is changed and the new changed value needs to be passed to the next call to this function. Since this function runs a complete DES ECB encryption per numbits, this function is only suggested for use when sending a small number of characters.

DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output Feed Back mode.

DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as DES_ofb64_encrypt(), using Triple-DES.

The following functions are included in the DES library for compatibility with the MIT Kerberos library.

DES_cbc_cksum() produces an 8 byte checksum based on the input stream (via CBC encryption). The last 4 bytes of the checksum are returned and the complete 8 bytes are placed in output. This function is used by Kerberos v4. Other applications should use EVP_DigestInit(3) etc. instead.

DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte checksum from the input bytes. The algorithm can be iterated over the input, depending on out_count, 1, 2, 3 or 4 times. If output is non-NULL, the 8 bytes generated by each pass are written into output.

The following are DES-based transformations:

DES_fcrypt() is a fast version of the Unix crypt(3) function. This version takes only a small amount of space relative to other fast crypt() implementations. This is different to the normal crypt() in that the third parameter is the buffer that the return value is written into. It needs to be at least 14 bytes long. This function is thread safe, unlike the normal crypt().

DES_crypt() is a faster replacement for the normal system crypt(). This function calls DES_fcrypt() with a static array passed as the third parameter. This mostly emulates the normal non-thread-safe semantics of crypt(3). The salt must be two ASCII characters.

The values returned by DES_fcrypt() and DES_crypt() are terminated by NUL character.

DES_enc_write() writes len bytes to file descriptor fd from buffer buf. The data is encrypted via pcbc_encrypt (default) using sched for the key and iv as a starting vector. The actual data send down fd consists of 4 bytes (in network byte order) containing the length of the following encrypted data. The encrypted data then follows, padded with random data out to a multiple of 8 bytes.

"},{"location":"man3/DES_random_key/#bugs","title":"BUGS","text":"

DES_cbc_encrypt() does not modify ivec; use DES_ncbc_encrypt() instead.

DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. What this means is that if you set numbits to 12, and length to 2, the first 12 bits will come from the 1st input byte and the low half of the second input byte. The second 12 bits will have the low 8 bits taken from the 3rd input byte and the top 4 bits taken from the 4th input byte. The same holds for output. This function has been implemented this way because most people will be using a multiple of 8 and because once you get into pulling bytes input bytes apart things get ugly!

DES_string_to_key() is available for backward compatibility with the MIT library. New applications should use a cryptographic hash function. The same applies for DES_string_to_2key().

"},{"location":"man3/DES_random_key/#notes","title":"NOTES","text":"

The des library was written to be source code compatible with the MIT Kerberos library.

Applications should use the higher level functions EVP_EncryptInit(3) etc. instead of calling these functions directly.

Single-key DES is insecure due to its short key size. ECB mode is not suitable for most applications; see des_modes(7).

"},{"location":"man3/DES_random_key/#return-values","title":"RETURN VALUES","text":"

DES_set_key(), DES_key_sched(), and DES_set_key_checked() return 0 on success or negative values on error.

DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it is ok.

DES_cbc_cksum() and DES_quad_cksum() return 4-byte integer representing the last 4 bytes of the checksum of the input.

DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() - to a static buffer on success; otherwise they return NULL.

"},{"location":"man3/DES_random_key/#see-also","title":"SEE ALSO","text":"

des_modes(7), EVP_EncryptInit(3)

"},{"location":"man3/DES_random_key/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The requirement that the salt parameter to DES_crypt() and DES_fcrypt() be two ASCII characters was first enforced in OpenSSL 1.1.0. Previous versions tried to use the letter uppercase A if both character were not present, and could crash when given non-ASCII on some platforms.

"},{"location":"man3/DES_random_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/DH_generate_key/","title":"DH_generate_key","text":""},{"location":"man3/DH_generate_key/#name","title":"NAME","text":"

DH_generate_key, DH_compute_key, DH_compute_key_padded - perform Diffie-Hellman key exchange

"},{"location":"man3/DH_generate_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_generate_key(DH *dh);\n\nint DH_compute_key(unsigned char *key, const BIGNUM *pub_key, DH *dh);\n\nint DH_compute_key_padded(unsigned char *key, const BIGNUM *pub_key, DH *dh);\n
"},{"location":"man3/DH_generate_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3).

DH_generate_key() performs the first step of a Diffie-Hellman key exchange by generating private and public DH values. By calling DH_compute_key() or DH_compute_key_padded(), these are combined with the other party's public value to compute the shared key.

DH_generate_key() expects dh to contain the shared parameters dh->p and dh->g. It generates a random private DH value unless dh->priv_key is already set, and computes the corresponding public value dh->pub_key, which can then be published.

DH_compute_key() computes the shared secret from the private DH value in dh and the other party's public value in pub_key and stores it in key. key must point to DH_size(dh) bytes of memory. The padding style is RFC 5246 (8.1.2) that strips leading zero bytes. It is not constant time due to the leading zero bytes being stripped. The return value should be considered public.

DH_compute_key_padded() is similar but stores a fixed number of bytes. The padding style is NIST SP 800-56A (C.1) that retains leading zero bytes. It is constant time due to the leading zero bytes being retained. The return value should be considered public.

"},{"location":"man3/DH_generate_key/#return-values","title":"RETURN VALUES","text":"

DH_generate_key() returns 1 on success, 0 otherwise.

DH_compute_key() returns the size of the shared secret on success, -1 on error.

DH_compute_key_padded() returns DH_size(dh) on success, -1 on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DH_generate_key/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_derive(3), DH_new(3), ERR_get_error(3), RAND_bytes(3), DH_size(3)

"},{"location":"man3/DH_generate_key/#history","title":"HISTORY","text":"

DH_compute_key_padded() was added in OpenSSL 1.0.2.

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_generate_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DH_generate_parameters/","title":"DH_generate_parameters","text":""},{"location":"man3/DH_generate_parameters/#name","title":"NAME","text":"

DH_generate_parameters_ex, DH_generate_parameters, DH_check, DH_check_params, DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex - generate and check Diffie-Hellman parameters

"},{"location":"man3/DH_generate_parameters/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);\n\nint DH_check(DH *dh, int *codes);\nint DH_check_params(DH *dh, int *codes);\n\nint DH_check_ex(const DH *dh);\nint DH_check_params_ex(const DH *dh);\nint DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DH_generate_parameters(int prime_len, int generator,\n                           void (*callback)(int, int, void *), void *cb_arg);\n
"},{"location":"man3/DH_generate_parameters/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_check(3), EVP_PKEY_public_check(3), EVP_PKEY_private_check(3) and EVP_PKEY_param_check(3).

DH_generate_parameters_ex() generates Diffie-Hellman parameters that can be shared among a group of users, and stores them in the provided DH structure. The pseudo-random number generator must be seeded before calling it. The parameters generated by DH_generate_parameters_ex() should not be used in signature schemes.

prime_len is the length in bits of the safe prime to be generated. generator is a small number > 1, typically 2 or 5.

A callback function may be used to provide feedback about the progress of the key generation. If cb is not NULL, it will be called as described in BN_generate_prime(3) while a random prime number is generated, and when a prime has been found, BN_GENCB_call(cb, 3, 0) is called. See BN_generate_prime_ex(3) for information on the BN_GENCB_call() function.

DH_generate_parameters() is similar to DH_generate_prime_ex() but expects an old-style callback function; see BN_generate_prime(3) for information on the old-style callback.

DH_check_params() confirms that the p and g are likely enough to be valid. This is a lightweight check, if a more thorough check is needed, use DH_check(). The value of *codes is updated with any problems found. If *codes is zero then no problems were found, otherwise the following bits may be set:

DH_check() confirms that the Diffie-Hellman parameters dh are valid. The value of *codes is updated with any problems found. If *codes is zero then no problems were found, otherwise the following bits may be set:

If 0 is returned or *codes is set to a nonzero value the supplied parameters should not be used for Diffie-Hellman operations otherwise the security properties of the key exchange are not guaranteed.

DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similar to DH_check() and DH_check_params() respectively, but the error reasons are added to the thread's error queue instead of provided as return values from the function.

"},{"location":"man3/DH_generate_parameters/#return-values","title":"RETURN VALUES","text":"

DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 if the check could be performed, 0 otherwise.

DH_generate_parameters() returns a pointer to the DH structure or NULL if the parameter generation fails.

DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() return 1 if the check is successful, 0 for failed.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DH_generate_parameters/#see-also","title":"SEE ALSO","text":"

DH_new(3), ERR_get_error(3), RAND_bytes(3), DH_free(3)

"},{"location":"man3/DH_generate_parameters/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

DH_generate_parameters() was deprecated in OpenSSL 0.9.8; use DH_generate_parameters_ex() instead.

"},{"location":"man3/DH_generate_parameters/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/DH_get0_pqg/","title":"DH_get0_pqg","text":""},{"location":"man3/DH_get0_pqg/#name","title":"NAME","text":"

DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_get0_p, DH_get0_q, DH_get0_g, DH_get0_priv_key, DH_get0_pub_key, DH_clear_flags, DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length, DH_set_length - Routines for getting and setting data in a DH object

"},{"location":"man3/DH_get0_pqg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DH_get0_pqg(const DH *dh,\n                 const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);\nint DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);\nvoid DH_get0_key(const DH *dh,\n                 const BIGNUM **pub_key, const BIGNUM **priv_key);\nint DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);\nconst BIGNUM *DH_get0_p(const DH *dh);\nconst BIGNUM *DH_get0_q(const DH *dh);\nconst BIGNUM *DH_get0_g(const DH *dh);\nconst BIGNUM *DH_get0_priv_key(const DH *dh);\nconst BIGNUM *DH_get0_pub_key(const DH *dh);\nvoid DH_clear_flags(DH *dh, int flags);\nint DH_test_flags(const DH *dh, int flags);\nvoid DH_set_flags(DH *dh, int flags);\n\nlong DH_get_length(const DH *dh);\nint DH_set_length(DH *dh, long length);\n\nENGINE *DH_get0_engine(DH *d);\n
"},{"location":"man3/DH_get0_pqg/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bn_param(3) for any methods that return a BIGNUM. Refer to EVP_PKEY-DH(7) for more information.

A DH object contains the parameters p, q and g. Note that the q parameter is optional. It also contains a public key (pub_key) and (optionally) a private key (priv_key).

The p, q and g parameters can be obtained by calling DH_get0_pqg(). If the parameters have not yet been set then *p, *q and *g will be set to NULL. Otherwise they are set to pointers to their respective values. These point directly to the internal representations of the values and therefore should not be freed directly. Any of the out parameters p, q, and g can be NULL, in which case no value will be returned for that parameter.

The p, q and g values can be set by calling DH_set0_pqg() and passing the new values for p, q and g as parameters to the function. Calling this function transfers the memory management of the values to the DH object, and therefore the values that have been passed in should not be freed directly after this function has been called. The q parameter may be NULL. DH_set0_pqg() also checks if the parameters associated with p and g and optionally q are associated with known safe prime groups. If it is a safe prime group then the value of q will be set to q = (p - 1) / 2 if q is NULL. The optional length parameter will be set to BN_num_bits(q) if q is not NULL.

To get the public and private key values use the DH_get0_key() function. A pointer to the public key will be stored in *pub_key, and a pointer to the private key will be stored in *priv_key. Either may be NULL if they have not been set yet, although if the private key has been set then the public key must be. The values point to the internal representation of the public key and private key values. This memory should not be freed directly. Any of the out parameters pub_key and priv_key can be NULL, in which case no value will be returned for that parameter.

The public and private key values can be set using DH_set0_key(). Either parameter may be NULL, which means the corresponding DH field is left untouched. As with DH_set0_pqg() this function transfers the memory management of the key values to the DH object, and therefore they should not be freed directly after this function has been called.

Any of the values p, q, g, priv_key, and pub_key can also be retrieved separately by the corresponding function DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_priv_key(), and DH_get0_pub_key(), respectively.

DH_set_flags() sets the flags in the flags parameter on the DH object. Multiple flags can be passed in one go (bitwise ORed together). Any flags that are already set are left set. DH_test_flags() tests to see whether the flags passed in the flags parameter are currently set in the DH object. Multiple flags can be tested in one go. All flags that are currently set are returned, or zero if none of the flags are set. DH_clear_flags() clears the specified flags within the DH object.

DH_get0_engine() returns a handle to the ENGINE that has been set for this DH object, or NULL if no such ENGINE has been set. This function is deprecated. All engines should be replaced by providers.

The DH_get_length() and DH_set_length() functions get and set the optional length parameter associated with this DH object. If the length is nonzero then it is used, otherwise it is ignored. The length parameter indicates the length of the secret exponent (private key) in bits. For safe prime groups the optional length parameter length can be set to a value greater or equal to 2 * maximum_target_security_strength(BN_num_bits(p)) as listed in SP800-56Ar3 Table(s) 25 & 26. These functions are deprecated and should be replaced with EVP_PKEY_CTX_set_params() and EVP_PKEY_get_int_param() using the parameter key OSSL_PKEY_PARAM_DH_PRIV_LEN as described in EVP_PKEY-DH(7).

"},{"location":"man3/DH_get0_pqg/#notes","title":"NOTES","text":"

Values retrieved with DH_get0_key() are owned by the DH object used in the call and may therefore not be passed to DH_set0_key(). If needed, duplicate the received value using BN_dup() and pass the duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg().

"},{"location":"man3/DH_get0_pqg/#return-values","title":"RETURN VALUES","text":"

DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.

DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_priv_key(), and DH_get0_pub_key() return the respective value, or NULL if it is unset.

DH_test_flags() returns the current state of the flags in the DH object.

DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE has been set.

DH_get_length() returns the length of the secret exponent (private key) in bits, or zero if no such length has been explicitly set.

"},{"location":"man3/DH_get0_pqg/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_generate_parameters(3), DH_generate_key(3), DH_set_method(3), DH_size(3), DH_meth_new(3)

"},{"location":"man3/DH_get0_pqg/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_get0_pqg/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2022 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.

"},{"location":"man3/DH_get_1024_160/","title":"DH_get_1024_160","text":""},{"location":"man3/DH_get_1024_160/#name","title":"NAME","text":"

DH_get_1024_160, DH_get_2048_224, DH_get_2048_256, BN_get0_nist_prime_192, BN_get0_nist_prime_224, BN_get0_nist_prime_256, BN_get0_nist_prime_384, BN_get0_nist_prime_521, BN_get_rfc2409_prime_768, BN_get_rfc2409_prime_1024, BN_get_rfc3526_prime_1536, BN_get_rfc3526_prime_2048, BN_get_rfc3526_prime_3072, BN_get_rfc3526_prime_4096, BN_get_rfc3526_prime_6144, BN_get_rfc3526_prime_8192 - Create standardized public primes or DH pairs

"},{"location":"man3/DH_get_1024_160/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n\nconst BIGNUM *BN_get0_nist_prime_192(void);\nconst BIGNUM *BN_get0_nist_prime_224(void);\nconst BIGNUM *BN_get0_nist_prime_256(void);\nconst BIGNUM *BN_get0_nist_prime_384(void);\nconst BIGNUM *BN_get0_nist_prime_521(void);\n\nBIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn);\nBIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/dh.h>\n\nDH *DH_get_1024_160(void);\nDH *DH_get_2048_224(void);\nDH *DH_get_2048_256(void);\n
"},{"location":"man3/DH_get_1024_160/#description","title":"DESCRIPTION","text":"

DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return a DH object for the IETF RFC 5114 value. These functions are deprecated. Applications should instead use EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() as described in EVP_PKEY_CTX_ctrl(3) or by setting the OSSL_PKEY_PARAM_GROUP_NAME as specified in \"DH parameters\" in EVP_PKEY-DH(7)) to one of \"dh_1024_160\", \"dh_2048_224\" or \"dh_2048_256\".

BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(), BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return a BIGNUM for the specific NIST prime curve (e.g., P-256).

BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(), BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(), BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(), BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions return a BIGNUM for the specified size from IETF RFC 2409. If bn is not NULL, the BIGNUM will be set into that location as well.

"},{"location":"man3/DH_get_1024_160/#return-values","title":"RETURN VALUES","text":"

Defined above.

"},{"location":"man3/DH_get_1024_160/#history","title":"HISTORY","text":"

The functions DH_get_1024_160(), DH_get_2048_224() and DH_get_2048_256() were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_get_1024_160/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 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.

"},{"location":"man3/DH_meth_new/","title":"DH_meth_new","text":""},{"location":"man3/DH_meth_new/#name","title":"NAME","text":"

DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, DH_meth_set_finish, DH_meth_get_generate_params, DH_meth_set_generate_params - Routines to build up DH methods

"},{"location":"man3/DH_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH_METHOD *DH_meth_new(const char *name, int flags);\n\nvoid DH_meth_free(DH_METHOD *dhm);\n\nDH_METHOD *DH_meth_dup(const DH_METHOD *dhm);\n\nconst char *DH_meth_get0_name(const DH_METHOD *dhm);\nint DH_meth_set1_name(DH_METHOD *dhm, const char *name);\n\nint DH_meth_get_flags(const DH_METHOD *dhm);\nint DH_meth_set_flags(DH_METHOD *dhm, int flags);\n\nvoid *DH_meth_get0_app_data(const DH_METHOD *dhm);\nint DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);\n\nint (*DH_meth_get_generate_key(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key)(DH *));\n\nint (*DH_meth_get_compute_key(const DH_METHOD *dhm))\n    (unsigned char *key, const BIGNUM *pub_key, DH *dh);\nint DH_meth_set_compute_key(DH_METHOD *dhm,\n    int (*compute_key)(unsigned char *key, const BIGNUM *pub_key, DH *dh));\n\nint (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))\n    (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\n     const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);\nint DH_meth_set_bn_mod_exp(DH_METHOD *dhm,\n    int (*bn_mod_exp)(const DH *dh, BIGNUM *r, const BIGNUM *a,\n                      const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,\n                      BN_MONT_CTX *m_ctx));\n\nint (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));\n\nint (*DH_meth_get_finish(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_finish(DH_METHOD *dhm, int (*finish)(DH *));\n\nint (*DH_meth_get_generate_params(const DH_METHOD *dhm))\n    (DH *, int, int, BN_GENCB *);\nint DH_meth_set_generate_params(DH_METHOD *dhm,\n    int (*generate_params)(DH *, int, int, BN_GENCB *));\n
"},{"location":"man3/DH_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

The DH_METHOD type is a structure used for the provision of custom DH implementations. It provides a set of functions used by OpenSSL for the implementation of the various DH capabilities.

DH_meth_new() creates a new DH_METHOD structure. It should be given a unique name and a set of flags. The name should be a NULL terminated string, which will be duplicated and stored in the DH_METHOD object. It is the callers responsibility to free the original string. The flags will be used during the construction of a new DH object based on this DH_METHOD. Any new DH object will have those flags set by default.

DH_meth_dup() creates a duplicate copy of the DH_METHOD object passed as a parameter. This might be useful for creating a new DH_METHOD based on an existing one, but with some differences.

DH_meth_free() destroys a DH_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This is a pointer to the internal name string and so should not be freed by the caller. DH_meth_set1_name() sets the name of the DH_METHOD to name. The string is duplicated and the copy is stored in the DH_METHOD structure, so the caller remains responsible for freeing the memory associated with the name.

DH_meth_get_flags() returns the current value of the flags associated with this DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.

The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the ability to associate implementation specific data with the DH_METHOD. It is the application's responsibility to free this data before the DH_METHOD is freed via a call to DH_meth_free().

DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the function used for generating a new DH key pair respectively. This function will be called in response to the application calling DH_generate_key(). The parameter for the function has the same meaning as for DH_generate_key().

DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the function used for computing a new DH shared secret respectively. This function will be called in response to the application calling DH_compute_key(). The parameters for the function have the same meaning as for DH_compute_key().

DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function used for computing the following value:

r = a ^ p mod m\n

This function will be called by the default OpenSSL function for DH_generate_key(). The result is stored in the r parameter. This function may be NULL unless using the default generate key function, in which case it must be present.

DH_meth_get_init() and DH_meth_set_init() get and set the function used for creating a new DH instance respectively. This function will be called in response to the application calling DH_new() (if the current default DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method() functions will allocate the memory for the new DH object, and a pointer to this newly allocated structure will be passed as a parameter to the function. This function may be NULL.

DH_meth_get_finish() and DH_meth_set_finish() get and set the function used for destroying an instance of a DH object respectively. This function will be called in response to the application calling DH_free(). A pointer to the DH to be destroyed is passed as a parameter. The destroy function should be used for DH implementation specific clean up. The memory for the DH itself should not be freed by this function. This function may be NULL.

DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the function used for generating DH parameters respectively. This function will be called in response to the application calling DH_generate_parameters_ex() (or DH_generate_parameters()). The parameters for the function have the same meaning as for DH_generate_parameters_ex(). This function may be NULL.

"},{"location":"man3/DH_meth_new/#return-values","title":"RETURN VALUES","text":"

DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object or NULL on failure.

DH_meth_get0_name() and DH_meth_get_flags() return the name and flags associated with the DH_METHOD respectively.

All other DH_meth_get_*() functions return the appropriate function pointer that has been set in the DH_METHOD, or NULL if no such pointer has yet been set.

DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or 0 on failure.

"},{"location":"man3/DH_meth_new/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_generate_parameters(3), DH_generate_key(3), DH_set_method(3), DH_size(3), DH_get0_pqg(3)

"},{"location":"man3/DH_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/DH_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/DH_new/","title":"DH_new","text":""},{"location":"man3/DH_new/#name","title":"NAME","text":"

DH_new, DH_free - allocate and free DH objects

"},{"location":"man3/DH_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH* DH_new(void);\n\nvoid DH_free(DH *dh);\n
"},{"location":"man3/DH_new/#description","title":"DESCRIPTION","text":"

DH_new() allocates and initializes a DH structure.

DH_free() frees the DH structure and its components. The values are erased before the memory is returned to the system. If dh is NULL nothing is done.

"},{"location":"man3/DH_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DH_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DH_free() returns no value.

"},{"location":"man3/DH_new/#see-also","title":"SEE ALSO","text":"

DH_new(3), ERR_get_error(3), DH_generate_parameters(3), DH_generate_key(3), EVP_PKEY-DH(7)

"},{"location":"man3/DH_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

For replacement see EVP_PKEY-DH(7).

"},{"location":"man3/DH_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/DH_new_by_nid/","title":"DH_new_by_nid","text":""},{"location":"man3/DH_new_by_nid/#name","title":"NAME","text":"

DH_new_by_nid, DH_get_nid - create or get DH named parameters

"},{"location":"man3/DH_new_by_nid/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DH_new_by_nid(int nid);\n\nint DH_get_nid(const DH *dh);\n
"},{"location":"man3/DH_new_by_nid/#description","title":"DESCRIPTION","text":"

DH_new_by_nid() creates and returns a DH structure containing named parameters nid. Currently nid must be NID_ffdhe2048, NID_ffdhe3072, NID_ffdhe4096, NID_ffdhe6144, NID_ffdhe8192, NID_modp_1536, NID_modp_2048, NID_modp_3072, NID_modp_4096, NID_modp_6144 or NID_modp_8192.

DH_get_nid() determines if the parameters contained in dh match any named safe prime group. It returns the NID corresponding to the matching parameters or NID_undef if there is no match. This function is deprecated.

"},{"location":"man3/DH_new_by_nid/#return-values","title":"RETURN VALUES","text":"

DH_new_by_nid() returns a set of DH parameters or NULL if an error occurred.

DH_get_nid() returns the NID of the matching set of parameters for p and g and optionally q, otherwise it returns NID_undef if there is no match.

"},{"location":"man3/DH_new_by_nid/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_new_by_nid/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/DH_set_method/","title":"DH_set_method","text":""},{"location":"man3/DH_set_method/#name","title":"NAME","text":"

DH_set_default_method, DH_get_default_method, DH_set_method, DH_new_method, DH_OpenSSL - select DH method

"},{"location":"man3/DH_set_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DH_set_default_method(const DH_METHOD *meth);\n\nconst DH_METHOD *DH_get_default_method(void);\n\nint DH_set_method(DH *dh, const DH_METHOD *meth);\n\nDH *DH_new_method(ENGINE *engine);\n\nconst DH_METHOD *DH_OpenSSL(void);\n
"},{"location":"man3/DH_set_method/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

A DH_METHOD specifies the functions that OpenSSL uses for Diffie-Hellman operations. By modifying the method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the NOTES section for important information about how these DH API functions are affected by the use of ENGINE API calls.

Initially, the default DH_METHOD is the OpenSSL internal implementation, as returned by DH_OpenSSL().

DH_set_default_method() makes meth the default method for all DH structures created later. NB: This is true only whilst no ENGINE has been set as a default for DH, so this function is no longer recommended. This function is not thread-safe and should not be called at the same time as other OpenSSL functions.

DH_get_default_method() returns a pointer to the current default DH_METHOD. However, the meaningfulness of this result is dependent on whether the ENGINE API is being used, so this function is no longer recommended.

DH_set_method() selects meth to perform all operations using the key dh. This will replace the DH_METHOD used by the DH key and if the previous method was supplied by an ENGINE, the handle to that ENGINE will be released during the change. It is possible to have DH keys that only work with certain DH_METHOD implementations (e.g. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DH_METHOD for the key can have unexpected results.

DH_new_method() allocates and initializes a DH structure so that engine will be used for the DH operations. If engine is NULL, the default ENGINE for DH operations is used, and if no default ENGINE is set, the DH_METHOD controlled by DH_set_default_method() is used.

A new DH_METHOD object may be constructed using DH_meth_new() (see DH_meth_new(3)).

"},{"location":"man3/DH_set_method/#return-values","title":"RETURN VALUES","text":"

DH_OpenSSL() and DH_get_default_method() return pointers to the respective DH_METHODs.

DH_set_default_method() returns no value.

DH_set_method() returns nonzero if the provided meth was successfully set as the method for dh (including unloading the ENGINE handle if the previous method was supplied by an ENGINE).

DH_new_method() returns NULL and sets an error code that can be obtained by ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly allocated structure.

"},{"location":"man3/DH_set_method/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_meth_new(3)

"},{"location":"man3/DH_set_method/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_set_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/DH_size/","title":"DH_size","text":""},{"location":"man3/DH_size/#name","title":"NAME","text":"

DH_size, DH_bits, DH_security_bits - get Diffie-Hellman prime size and security bits

"},{"location":"man3/DH_size/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_bits(const DH *dh);\n\nint DH_size(const DH *dh);\n\nint DH_security_bits(const DH *dh);\n
"},{"location":"man3/DH_size/#description","title":"DESCRIPTION","text":"

The functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and EVP_PKEY_get_size(3).

DH_bits() returns the number of significant bits.

dh and dh->p must not be NULL.

DH_size() returns the Diffie-Hellman prime size in bytes. It can be used to determine how much memory must be allocated for the shared secret computed by DH_compute_key(3).

DH_security_bits() returns the number of security bits of the given dh key. See BN_security_bits(3).

"},{"location":"man3/DH_size/#return-values","title":"RETURN VALUES","text":"

DH_bits() returns the number of bits in the key, or -1 if dh doesn't hold any key parameters.

DH_size() returns the prime size of Diffie-Hellman in bytes, or -1 if dh doesn't hold any key parameters.

DH_security_bits() returns the number of security bits, or -1 if dh doesn't hold any key parameters.

"},{"location":"man3/DH_size/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bits(3), DH_new(3), DH_generate_key(3), BN_num_bits(3)

"},{"location":"man3/DH_size/#history","title":"HISTORY","text":"

All functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_size/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_SIG_new/","title":"DSA_SIG_new","text":""},{"location":"man3/DSA_SIG_new/#name","title":"NAME","text":"

DSA_SIG_get0, DSA_SIG_set0, DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects

"},{"location":"man3/DSA_SIG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n\nDSA_SIG *DSA_SIG_new(void);\nvoid DSA_SIG_free(DSA_SIG *a);\nvoid DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);\nint DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);\n
"},{"location":"man3/DSA_SIG_new/#description","title":"DESCRIPTION","text":"

DSA_SIG_new() allocates an empty DSA_SIG structure.

DSA_SIG_free() frees the DSA_SIG structure and its components. The values are erased before the memory is returned to the system. If the argument is NULL, nothing is done.

DSA_SIG_get0() returns internal pointers to the r and s values contained in sig.

The r and s values can be set by calling DSA_SIG_set0() and passing the new values for r and s as parameters to the function. Calling this function transfers the memory management of the values to the DSA_SIG object, and therefore the values that have been passed in should not be freed directly after this function has been called.

"},{"location":"man3/DSA_SIG_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DSA_SIG_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DSA_SIG_free() returns no value.

DSA_SIG_set0() returns 1 on success or 0 on failure.

"},{"location":"man3/DSA_SIG_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), EVP_PKEY_free(3), EVP_PKEY_get_bn_param(3), ERR_get_error(3)

"},{"location":"man3/DSA_SIG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/DSA_do_sign/","title":"DSA_do_sign","text":""},{"location":"man3/DSA_do_sign/#name","title":"NAME","text":"

DSA_do_sign, DSA_do_verify - raw DSA signature operations

"},{"location":"man3/DSA_do_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);\n\nint DSA_do_verify(const unsigned char *dgst, int dgst_len,\n                  DSA_SIG *sig, DSA *dsa);\n
"},{"location":"man3/DSA_do_sign/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_sign_init(3), EVP_PKEY_sign(3), EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

DSA_do_sign() computes a digital signature on the len byte message digest dgst using the private key dsa and returns it in a newly allocated DSA_SIG structure.

DSA_sign_setup(3) may be used to precompute part of the signing operation in case signature generation is time-critical.

DSA_do_verify() verifies that the signature sig matches a given message digest dgst of size len. dsa is the signer's public key.

"},{"location":"man3/DSA_do_sign/#return-values","title":"RETURN VALUES","text":"

DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_do_sign/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_SIG_new(3), DSA_sign(3)

"},{"location":"man3/DSA_do_sign/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_do_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_dup_DH/","title":"DSA_dup_DH","text":""},{"location":"man3/DSA_dup_DH/#name","title":"NAME","text":"

DSA_dup_DH - create a DH structure out of DSA structure

"},{"location":"man3/DSA_dup_DH/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DSA_dup_DH(const DSA *r);\n
"},{"location":"man3/DSA_dup_DH/#description","title":"DESCRIPTION","text":"

The function described on this page is deprecated. There is no direct replacement, applications should use the EVP_PKEY APIs for Diffie-Hellman operations.

DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q is lost during that conversion, but the resulting DH parameters contain its length.

"},{"location":"man3/DSA_dup_DH/#return-values","title":"RETURN VALUES","text":"

DSA_dup_DH() returns the new DH structure, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_dup_DH/#note","title":"NOTE","text":"

Be careful to avoid small subgroup attacks when using this.

"},{"location":"man3/DSA_dup_DH/#see-also","title":"SEE ALSO","text":"

DH_new(3), DSA_new(3), ERR_get_error(3)

"},{"location":"man3/DSA_dup_DH/#history","title":"HISTORY","text":"

This function was deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_dup_DH/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/DSA_generate_key/","title":"DSA_generate_key","text":""},{"location":"man3/DSA_generate_key/#name","title":"NAME","text":"

DSA_generate_key - generate DSA key pair

"},{"location":"man3/DSA_generate_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_generate_key(DSA *a);\n
"},{"location":"man3/DSA_generate_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3) as described in EVP_PKEY-DSA(7).

DSA_generate_key() expects a to contain DSA parameters. It generates a new key pair and stores it in a->pub_key and a->priv_key.

The random generator must be seeded prior to calling DSA_generate_key(). If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

"},{"location":"man3/DSA_generate_key/#return-values","title":"RETURN VALUES","text":"

DSA_generate_key() returns 1 on success, 0 otherwise. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_generate_key/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_generate_parameters_ex(3)

"},{"location":"man3/DSA_generate_key/#history","title":"HISTORY","text":"

This function was deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_generate_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_generate_parameters/","title":"DSA_generate_parameters","text":""},{"location":"man3/DSA_generate_parameters/#name","title":"NAME","text":"

DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters

"},{"location":"man3/DSA_generate_parameters/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_generate_parameters_ex(DSA *dsa, int bits,\n                               const unsigned char *seed, int seed_len,\n                               int *counter_ret, unsigned long *h_ret,\n                               BN_GENCB *cb);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len,\n                             int *counter_ret, unsigned long *h_ret,\n                             void (*callback)(int, int, void *), void *cb_arg);\n
"},{"location":"man3/DSA_generate_parameters/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_paramgen_init(3) and EVP_PKEY_keygen(3) as described in EVP_PKEY-DSA(7).

DSA_generate_parameters_ex() generates primes p and q and a generator g for use in the DSA and stores the result in dsa.

bits is the length of the prime p to be generated. For lengths under 2048 bits, the length of q is 160 bits; for lengths greater than or equal to 2048 bits, the length of q is set to 256 bits.

If seed is NULL, the primes will be generated at random. If seed_len is less than the length of q, an error is returned.

DSA_generate_parameters_ex() places the iteration count in *counter_ret and a counter used for finding a generator in *h_ret, unless these are NULL.

A callback function may be used to provide feedback about the progress of the key generation. If cb is not NULL, it will be called as shown below. For information on the BN_GENCB structure and the BN_GENCB_call function discussed below, refer to BN_generate_prime(3).

DSA_generate_parameters() is similar to DSA_generate_parameters_ex() but expects an old-style callback function; see BN_generate_prime(3) for information on the old-style callback.

"},{"location":"man3/DSA_generate_parameters/#return-values","title":"RETURN VALUES","text":"

DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. The error codes can be obtained by ERR_get_error(3).

DSA_generate_parameters() returns a pointer to the DSA structure or NULL if the parameter generation fails.

"},{"location":"man3/DSA_generate_parameters/#bugs","title":"BUGS","text":"

Seed lengths greater than 20 are not supported.

"},{"location":"man3/DSA_generate_parameters/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_free(3), BN_generate_prime(3)

"},{"location":"man3/DSA_generate_parameters/#history","title":"HISTORY","text":"

DSA_generate_parameters_ex() was deprecated in OpenSSL 3.0.

DSA_generate_parameters() was deprecated in OpenSSL 0.9.8; use DSA_generate_parameters_ex() instead.

"},{"location":"man3/DSA_generate_parameters/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_get0_pqg/","title":"DSA_get0_pqg","text":""},{"location":"man3/DSA_get0_pqg/#name","title":"NAME","text":"

DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_get0_p, DSA_get0_q, DSA_get0_g, DSA_get0_pub_key, DSA_get0_priv_key, DSA_clear_flags, DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and setting data in a DSA object

"},{"location":"man3/DSA_get0_pqg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DSA_get0_pqg(const DSA *d,\n                  const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);\nint DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g);\nvoid DSA_get0_key(const DSA *d,\n                  const BIGNUM **pub_key, const BIGNUM **priv_key);\nint DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key);\nconst BIGNUM *DSA_get0_p(const DSA *d);\nconst BIGNUM *DSA_get0_q(const DSA *d);\nconst BIGNUM *DSA_get0_g(const DSA *d);\nconst BIGNUM *DSA_get0_pub_key(const DSA *d);\nconst BIGNUM *DSA_get0_priv_key(const DSA *d);\nvoid DSA_clear_flags(DSA *d, int flags);\nint DSA_test_flags(const DSA *d, int flags);\nvoid DSA_set_flags(DSA *d, int flags);\nENGINE *DSA_get0_engine(DSA *d);\n
"},{"location":"man3/DSA_get0_pqg/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bn_param(3).

A DSA object contains the parameters p, q and g. It also contains a public key (pub_key) and (optionally) a private key (priv_key).

The p, q and g parameters can be obtained by calling DSA_get0_pqg(). If the parameters have not yet been set then *p, *q and *g will be set to NULL. Otherwise they are set to pointers to their respective values. These point directly to the internal representations of the values and therefore should not be freed directly.

The p, q and g values can be set by calling DSA_set0_pqg() and passing the new values for p, q and g as parameters to the function. Calling this function transfers the memory management of the values to the DSA object, and therefore the values that have been passed in should not be freed directly after this function has been called.

To get the public and private key values use the DSA_get0_key() function. A pointer to the public key will be stored in *pub_key, and a pointer to the private key will be stored in *priv_key. Either may be NULL if they have not been set yet, although if the private key has been set then the public key must be. The values point to the internal representation of the public key and private key values. This memory should not be freed directly.

The public and private key values can be set using DSA_set0_key(). The public key must be non-NULL the first time this function is called on a given DSA object. The private key may be NULL. On subsequent calls, either may be NULL, which means the corresponding DSA field is left untouched. As for DSA_set0_pqg() this function transfers the memory management of the key values to the DSA object, and therefore they should not be freed directly after this function has been called.

Any of the values p, q, g, priv_key, and pub_key can also be retrieved separately by the corresponding function DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_priv_key(), and DSA_get0_pub_key(), respectively.

DSA_set_flags() sets the flags in the flags parameter on the DSA object. Multiple flags can be passed in one go (bitwise ORed together). Any flags that are already set are left set. DSA_test_flags() tests to see whether the flags passed in the flags parameter are currently set in the DSA object. Multiple flags can be tested in one go. All flags that are currently set are returned, or zero if none of the flags are set. DSA_clear_flags() clears the specified flags within the DSA object.

DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA object, or NULL if no such ENGINE has been set.

"},{"location":"man3/DSA_get0_pqg/#notes","title":"NOTES","text":"

Values retrieved with DSA_get0_key() are owned by the DSA object used in the call and may therefore not be passed to DSA_set0_key(). If needed, duplicate the received value using BN_dup() and pass the duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg().

"},{"location":"man3/DSA_get0_pqg/#return-values","title":"RETURN VALUES","text":"

DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.

DSA_test_flags() returns the current state of the flags in the DSA object.

DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE has been set.

"},{"location":"man3/DSA_get0_pqg/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bn_param(3), DSA_new(3), DSA_new(3), DSA_generate_parameters(3), DSA_generate_key(3), DSA_dup_DH(3), DSA_do_sign(3), DSA_set_method(3), DSA_SIG_new(3), DSA_sign(3), DSA_size(3), DSA_meth_new(3)

"},{"location":"man3/DSA_get0_pqg/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0 and deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_get0_pqg/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2018 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.

"},{"location":"man3/DSA_meth_new/","title":"DSA_meth_new","text":""},{"location":"man3/DSA_meth_new/#name","title":"NAME","text":"

DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, DSA_meth_set_keygen - Routines to build up DSA methods

"},{"location":"man3/DSA_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA_METHOD *DSA_meth_new(const char *name, int flags);\n\nvoid DSA_meth_free(DSA_METHOD *dsam);\n\nDSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);\n\nconst char *DSA_meth_get0_name(const DSA_METHOD *dsam);\nint DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);\n\nint DSA_meth_get_flags(const DSA_METHOD *dsam);\nint DSA_meth_set_flags(DSA_METHOD *dsam, int flags);\n\nvoid *DSA_meth_get0_app_data(const DSA_METHOD *dsam);\nint DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);\n\nDSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))(const unsigned char *,\n                                                      int, DSA *);\nint DSA_meth_set_sign(DSA_METHOD *dsam, DSA_SIG *(*sign)(const unsigned char *,\n                                                         int, DSA *));\n\nint (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))(DSA *, BN_CTX *,$\n                                                       BIGNUM **, BIGNUM **);\nint DSA_meth_set_sign_setup(DSA_METHOD *dsam, int (*sign_setup)(DSA *, BN_CTX *,\n                                                                BIGNUM **, BIGNUM **));\n\nint (*DSA_meth_get_verify(const DSA_METHOD *dsam))(const unsigned char *,\n                                                   int, DSA_SIG *, DSA *);\nint DSA_meth_set_verify(DSA_METHOD *dsam, int (*verify)(const unsigned char *,\n                                                        int, DSA_SIG *, DSA *));\n\nint (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *rr, BIGNUM *a1,\n                                                    BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,\n                                                    BIGNUM *m, BN_CTX *ctx,\n                                                    BN_MONT_CTX *in_mont);\nint DSA_meth_set_mod_exp(DSA_METHOD *dsam, int (*mod_exp)(DSA *dsa, BIGNUM *rr,\n                                                          BIGNUM *a1, BIGNUM *p1,\n                                                          BIGNUM *a2, BIGNUM *p2,\n                                                          BIGNUM *m, BN_CTX *ctx,\n                                                          BN_MONT_CTX *mont));\n\nint (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *r, BIGNUM *a,\n                                                       const BIGNUM *p, const BIGNUM *m,\n                                                       BN_CTX *ctx, BN_MONT_CTX *mont);\nint DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, int (*bn_mod_exp)(DSA *dsa,\n                                                                BIGNUM *r,\n                                                                BIGNUM *a,\n                                                                const BIGNUM *p,\n                                                                const BIGNUM *m,\n                                                                BN_CTX *ctx,\n                                                                BN_MONT_CTX *mont));\n\nint (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));\n\nint (*DSA_meth_get_finish(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish)(DSA *));\n\nint (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))(DSA *, int,\n                                                     const unsigned char *,\n                                                     int, int *, unsigned long *,\n                                                     BN_GENCB *);\nint DSA_meth_set_paramgen(DSA_METHOD *dsam,\n                          int (*paramgen)(DSA *, int, const unsigned char *,\n                                          int, int *, unsigned long *, BN_GENCB *));\n\nint (*DSA_meth_get_keygen(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen)(DSA *));\n
"},{"location":"man3/DSA_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications and extension implementations should instead use the OSSL_PROVIDER APIs.

The DSA_METHOD type is a structure used for the provision of custom DSA implementations. It provides a set of functions used by OpenSSL for the implementation of the various DSA capabilities.

DSA_meth_new() creates a new DSA_METHOD structure. It should be given a unique name and a set of flags. The name should be a NULL terminated string, which will be duplicated and stored in the DSA_METHOD object. It is the callers responsibility to free the original string. The flags will be used during the construction of a new DSA object based on this DSA_METHOD. Any new DSA object will have those flags set by default.

DSA_meth_dup() creates a duplicate copy of the DSA_METHOD object passed as a parameter. This might be useful for creating a new DSA_METHOD based on an existing one, but with some differences.

DSA_meth_free() destroys a DSA_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This is a pointer to the internal name string and so should not be freed by the caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to name. The string is duplicated and the copy is stored in the DSA_METHOD structure, so the caller remains responsible for freeing the memory associated with the name.

DSA_meth_get_flags() returns the current value of the flags associated with this DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags.

The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the ability to associate implementation specific data with the DSA_METHOD. It is the application's responsibility to free this data before the DSA_METHOD is freed via a call to DSA_meth_free().

DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for creating a DSA signature respectively. This function will be called in response to the application calling DSA_do_sign() (or DSA_sign()). The parameters for the function have the same meaning as for DSA_do_sign().

DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function used for precalculating the DSA signature values k^-1 and r. This function will be called in response to the application calling DSA_sign_setup(). The parameters for the function have the same meaning as for DSA_sign_setup().

DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used for verifying a DSA signature respectively. This function will be called in response to the application calling DSA_do_verify() (or DSA_verify()). The parameters for the function have the same meaning as for DSA_do_verify().

DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used for computing the following value:

rr = a1^p1 * a2^p2 mod m\n

This function will be called by the default OpenSSL method during verification of a DSA signature. The result is stored in the rr parameter. This function may be NULL.

DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function used for computing the following value:

r = a ^ p mod m\n

This function will be called by the default OpenSSL function for DSA_sign_setup(). The result is stored in the r parameter. This function may be NULL.

DSA_meth_get_init() and DSA_meth_set_init() get and set the function used for creating a new DSA instance respectively. This function will be called in response to the application calling DSA_new() (if the current default DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method() functions will allocate the memory for the new DSA object, and a pointer to this newly allocated structure will be passed as a parameter to the function. This function may be NULL.

DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used for destroying an instance of a DSA object respectively. This function will be called in response to the application calling DSA_free(). A pointer to the DSA to be destroyed is passed as a parameter. The destroy function should be used for DSA implementation specific clean up. The memory for the DSA itself should not be freed by this function. This function may be NULL.

DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function used for generating DSA parameters respectively. This function will be called in response to the application calling DSA_generate_parameters_ex() (or DSA_generate_parameters()). The parameters for the function have the same meaning as for DSA_generate_parameters_ex().

DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function used for generating a new DSA key pair respectively. This function will be called in response to the application calling DSA_generate_key(). The parameter for the function has the same meaning as for DSA_generate_key().

"},{"location":"man3/DSA_meth_new/#return-values","title":"RETURN VALUES","text":"

DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object or NULL on failure.

DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags associated with the DSA_METHOD respectively.

All other DSA_meth_get_*() functions return the appropriate function pointer that has been set in the DSA_METHOD, or NULL if no such pointer has yet been set.

DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or 0 on failure.

"},{"location":"man3/DSA_meth_new/#see-also","title":"SEE ALSO","text":"

DSA_new(3), DSA_new(3), DSA_generate_parameters(3), DSA_generate_key(3), DSA_dup_DH(3), DSA_do_sign(3), DSA_set_method(3), DSA_SIG_new(3), DSA_sign(3), DSA_size(3), DSA_get0_pqg(3)

"},{"location":"man3/DSA_meth_new/#history","title":"HISTORY","text":"

The functions described here were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/DSA_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/DSA_new/","title":"DSA_new","text":""},{"location":"man3/DSA_new/#name","title":"NAME","text":"

DSA_new, DSA_free - allocate and free DSA objects

"},{"location":"man3/DSA_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA* DSA_new(void);\n\nvoid DSA_free(DSA *dsa);\n
"},{"location":"man3/DSA_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_new(3) and EVP_PKEY_free(3).

DSA_new() allocates and initializes a DSA structure. It is equivalent to calling DSA_new_method(NULL).

DSA_free() frees the DSA structure and its components. The values are erased before the memory is returned to the system. If dsa is NULL nothing is done.

"},{"location":"man3/DSA_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DSA_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DSA_free() returns no value.

"},{"location":"man3/DSA_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), EVP_PKEY_free(3), DSA_new(3), ERR_get_error(3), DSA_generate_parameters(3), DSA_generate_key(3)

"},{"location":"man3/DSA_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 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.

"},{"location":"man3/DSA_set_method/","title":"DSA_set_method","text":""},{"location":"man3/DSA_set_method/#name","title":"NAME","text":"

DSA_set_default_method, DSA_get_default_method, DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method

"},{"location":"man3/DSA_set_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DSA_set_default_method(const DSA_METHOD *meth);\n\nconst DSA_METHOD *DSA_get_default_method(void);\n\nint DSA_set_method(DSA *dsa, const DSA_METHOD *meth);\n\nDSA *DSA_new_method(ENGINE *engine);\n\nconst DSA_METHOD *DSA_OpenSSL(void);\n
"},{"location":"man3/DSA_set_method/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should providers instead of method overrides.

A DSA_METHOD specifies the functions that OpenSSL uses for DSA operations. By modifying the method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the NOTES section for important information about how these DSA API functions are affected by the use of ENGINE API calls.

Initially, the default DSA_METHOD is the OpenSSL internal implementation, as returned by DSA_OpenSSL().

DSA_set_default_method() makes meth the default method for all DSA structures created later. NB: This is true only whilst no ENGINE has been set as a default for DSA, so this function is no longer recommended. This function is not thread-safe and should not be called at the same time as other OpenSSL functions.

DSA_get_default_method() returns a pointer to the current default DSA_METHOD. However, the meaningfulness of this result is dependent on whether the ENGINE API is being used, so this function is no longer recommended.

DSA_set_method() selects meth to perform all operations using the key rsa. This will replace the DSA_METHOD used by the DSA key and if the previous method was supplied by an ENGINE, the handle to that ENGINE will be released during the change. It is possible to have DSA keys that only work with certain DSA_METHOD implementations (e.g. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DSA_METHOD for the key can have unexpected results. See DSA_meth_new(3) for information on constructing custom DSA_METHOD objects;

DSA_new_method() allocates and initializes a DSA structure so that engine will be used for the DSA operations. If engine is NULL, the default engine for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD controlled by DSA_set_default_method() is used.

"},{"location":"man3/DSA_set_method/#return-values","title":"RETURN VALUES","text":"

DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective DSA_METHODs.

DSA_set_default_method() returns no value.

DSA_set_method() returns nonzero if the provided meth was successfully set as the method for dsa (including unloading the ENGINE handle if the previous method was supplied by an ENGINE).

DSA_new_method() returns NULL and sets an error code that can be obtained by ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly allocated structure.

"},{"location":"man3/DSA_set_method/#see-also","title":"SEE ALSO","text":"

DSA_new(3), DSA_new(3), DSA_meth_new(3)

"},{"location":"man3/DSA_set_method/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_set_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_sign/","title":"DSA_sign","text":""},{"location":"man3/DSA_sign/#name","title":"NAME","text":"

DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures

"},{"location":"man3/DSA_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_sign(int type, const unsigned char *dgst, int len,\n             unsigned char *sigret, unsigned int *siglen, DSA *dsa);\n\nint DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, BIGNUM **rp);\n\nint DSA_verify(int type, const unsigned char *dgst, int len,\n               unsigned char *sigbuf, int siglen, DSA *dsa);\n
"},{"location":"man3/DSA_sign/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_sign_init(3), EVP_PKEY_sign(3), EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

DSA_sign() computes a digital signature on the len byte message digest dgst using the private key dsa and places its ASN.1 DER encoding at sigret. The length of the signature is places in *siglen. sigret must point to DSA_size(dsa) bytes of memory.

DSA_sign_setup() is defined only for backward binary compatibility and should not be used. Since OpenSSL 1.1.0 the DSA type is opaque and the output of DSA_sign_setup() cannot be used anyway: calling this function will only cause overhead, and does not affect the actual signature (pre-)computation.

DSA_verify() verifies that the signature sigbuf of size siglen matches a given message digest dgst of size len. dsa is the signer's public key.

The type parameter is ignored.

The random generator must be seeded when DSA_sign() (or DSA_sign_setup()) is called. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

"},{"location":"man3/DSA_sign/#return-values","title":"RETURN VALUES","text":"

DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. DSA_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_sign/#conforming-to","title":"CONFORMING TO","text":"

US Federal Information Processing Standard FIPS186-4 (Digital Signature Standard, DSS), ANSI X9.30

"},{"location":"man3/DSA_sign/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_do_sign(3), RAND(7)

"},{"location":"man3/DSA_sign/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DSA_size/","title":"DSA_size","text":""},{"location":"man3/DSA_size/#name","title":"NAME","text":"

DSA_size, DSA_bits, DSA_security_bits - get DSA signature size, key bits or security bits

"},{"location":"man3/DSA_size/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_bits(const DSA *dsa);\n\nint DSA_size(const DSA *dsa);\n\nint DSA_security_bits(const DSA *dsa);\n
"},{"location":"man3/DSA_size/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and EVP_PKEY_get_size(3).

DSA_bits() returns the number of bits in key dsa: this is the number of bits in the p parameter.

DSA_size() returns the maximum size of an ASN.1 encoded DSA signature for key dsa in bytes. It can be used to determine how much memory must be allocated for a DSA signature.

DSA_security_bits() returns the number of security bits of the given dsa key. See BN_security_bits(3).

"},{"location":"man3/DSA_size/#return-values","title":"RETURN VALUES","text":"

DSA_security_bits() returns the number of security bits in the key, or -1 if dsa doesn't hold any key parameters.

DSA_bits() returns the number of bits in the key, or -1 if dsa doesn't hold any key parameters.

DSA_size() returns the signature size in bytes, or -1 if dsa doesn't hold any key parameters.

"},{"location":"man3/DSA_size/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3), EVP_PKEY_get_size(3), DSA_new(3), DSA_sign(3)

"},{"location":"man3/DSA_size/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_size/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/DTLS_get_data_mtu/","title":"DTLS_get_data_mtu","text":""},{"location":"man3/DTLS_get_data_mtu/#name","title":"NAME","text":"

DTLS_get_data_mtu - Get maximum data payload size

"},{"location":"man3/DTLS_get_data_mtu/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nsize_t DTLS_get_data_mtu(const SSL *ssl);\n
"},{"location":"man3/DTLS_get_data_mtu/#description","title":"DESCRIPTION","text":"

This function obtains the maximum data payload size for the established DTLS connection ssl, based on the DTLS record MTU and the overhead of the DTLS record header, encryption and authentication currently in use.

"},{"location":"man3/DTLS_get_data_mtu/#return-values","title":"RETURN VALUES","text":"

Returns the maximum data payload size on success, or 0 on failure.

"},{"location":"man3/DTLS_get_data_mtu/#history","title":"HISTORY","text":"

The DTLS_get_data_mtu() function was added in OpenSSL 1.1.1.

"},{"location":"man3/DTLS_get_data_mtu/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/DTLS_set_timer_cb/","title":"DTLS_set_timer_cb","text":""},{"location":"man3/DTLS_set_timer_cb/#name","title":"NAME","text":"

DTLS_timer_cb, DTLS_set_timer_cb - Set callback for controlling DTLS timer duration

"},{"location":"man3/DTLS_set_timer_cb/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\ntypedef unsigned int (*DTLS_timer_cb)(SSL *s, unsigned int timer_us);\n\nvoid DTLS_set_timer_cb(SSL *s, DTLS_timer_cb cb);\n
"},{"location":"man3/DTLS_set_timer_cb/#description","title":"DESCRIPTION","text":"

This function sets an optional callback function for controlling the timeout interval on the DTLS protocol. The callback function will be called by DTLS for every new DTLS packet that is sent.

"},{"location":"man3/DTLS_set_timer_cb/#return-values","title":"RETURN VALUES","text":"

Returns void.

"},{"location":"man3/DTLS_set_timer_cb/#history","title":"HISTORY","text":"

The DTLS_set_timer_cb() function was added in OpenSSL 1.1.1.

"},{"location":"man3/DTLS_set_timer_cb/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/DTLSv1_get_timeout/","title":"DTLSv1_get_timeout","text":""},{"location":"man3/DTLSv1_get_timeout/#name","title":"NAME","text":"

DTLSv1_get_timeout - determine when a DTLS or QUIC SSL object next needs a timeout event to be handled

"},{"location":"man3/DTLSv1_get_timeout/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint DTLSv1_get_timeout(SSL *s, struct timeval *tv);\n
"},{"location":"man3/DTLSv1_get_timeout/#description","title":"DESCRIPTION","text":"

DTLSv1_get_timeout() can be used on a DTLS or QUIC SSL object to determine when the SSL object next needs to perform internal processing due to the passage of time.

Calling DTLSv1_get_timeout() results in *tv being written with an amount of time left before the SSL object needs have DTLSv1_handle_timeout() called on it. If the SSL object needs to be ticked immediately, *tv is zeroed and the function succeeds, returning 1. If no timeout is currently active, this function returns 0.

This function is only applicable to DTLS and QUIC objects. It fails if called on any other kind of SSL object.

Note that the value output by a call to DTLSv1_get_timeout() may change as a result of other calls to the SSL object.

Once the timeout expires, DTLSv1_handle_timeout() should be called to handle any internal processing which is due; for more information, see DTLSv1_handle_timeout(3).

SSL_get_event_timeout(3) supersedes all use cases for this this function and may be used instead of it.

"},{"location":"man3/DTLSv1_get_timeout/#return-values","title":"RETURN VALUES","text":"

On success, writes a duration to *tv and returns 1.

Returns 0 on failure, or if no timeout is currently active.

"},{"location":"man3/DTLSv1_get_timeout/#see-also","title":"SEE ALSO","text":"

DTLSv1_handle_timeout(3), SSL_get_event_timeout(3), ssl(7)

"},{"location":"man3/DTLSv1_get_timeout/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/DTLSv1_handle_timeout/","title":"DTLSv1_handle_timeout","text":""},{"location":"man3/DTLSv1_handle_timeout/#name","title":"NAME","text":"

DTLSv1_handle_timeout - handle a pending timeout event for a DTLS or QUIC SSL object

"},{"location":"man3/DTLSv1_handle_timeout/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint DTLSv1_handle_timeout(SSL *ssl);\n
"},{"location":"man3/DTLSv1_handle_timeout/#description","title":"DESCRIPTION","text":"

DTLSv1_handle_timeout() handles any timeout events which have become pending on a DTLS or QUIC SSL object.

Use DTLSv1_get_timeout(3) or SSL_get_event_timeout(3) to determine when to call DTLSv1_handle_timeout().

This function is only applicable to DTLS or QUIC SSL objects. It returns 0 if called on any other kind of SSL object.

SSL_handle_events(3) supersedes all use cases for this function and may be used instead of it.

"},{"location":"man3/DTLSv1_handle_timeout/#return-values","title":"RETURN VALUES","text":"

Returns 1 if there was a pending timeout event and it was handled successfully.

Returns 0 if there was no pending timeout event, or if the SSL object is not a DTLS or QUIC object.

Returns -1 if there was a pending timeout event but it could not be handled successfully.

"},{"location":"man3/DTLSv1_handle_timeout/#see-also","title":"SEE ALSO","text":"

DTLSv1_get_timeout(3), SSL_handle_events(3), ssl(7)

"},{"location":"man3/DTLSv1_handle_timeout/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/DTLSv1_listen/","title":"DTLSv1_listen","text":""},{"location":"man3/DTLSv1_listen/#name","title":"NAME","text":"

SSL_stateless, DTLSv1_listen - Statelessly listen for incoming connections

"},{"location":"man3/DTLSv1_listen/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint SSL_stateless(SSL *s);\nint DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);\n
"},{"location":"man3/DTLSv1_listen/#description","title":"DESCRIPTION","text":"

SSL_stateless() statelessly listens for new incoming TLSv1.3 connections. DTLSv1_listen() statelessly listens for new incoming DTLS connections. If a ClientHello is received that does not contain a cookie, then they respond with a request for a new ClientHello that does contain a cookie. If a ClientHello is received with a cookie that is verified then the function returns in order to enable the handshake to be completed (for example by using SSL_accept()).

"},{"location":"man3/DTLSv1_listen/#notes","title":"NOTES","text":"

Some transport protocols (such as UDP) can be susceptible to amplification attacks. Unlike TCP there is no initial connection setup in UDP that validates that the client can actually receive messages on its advertised source address. An attacker could forge its source IP address and then send handshake initiation messages to the server. The server would then send its response to the forged source IP. If the response messages are larger than the original message then the amplification attack has succeeded.

If DTLS is used over UDP (or any datagram based protocol that does not validate the source IP) then it is susceptible to this type of attack. TLSv1.3 is designed to operate over a stream-based transport protocol (such as TCP). If TCP is being used then there is no need to use SSL_stateless(). However, some stream-based transport protocols (e.g. QUIC) may not validate the source address. In this case a TLSv1.3 application would be susceptible to this attack.

As a countermeasure to this issue TLSv1.3 and DTLS include a stateless cookie mechanism. The idea is that when a client attempts to connect to a server it sends a ClientHello message. The server responds with a HelloRetryRequest (in TLSv1.3) or a HelloVerifyRequest (in DTLS) which contains a unique cookie. The client then resends the ClientHello, but this time includes the cookie in the message thus proving that the client is capable of receiving messages sent to that address. All of this can be done by the server without allocating any state, and thus without consuming expensive resources.

OpenSSL implements this capability via the SSL_stateless() and DTLSv1_listen() functions. The ssl parameter should be a newly allocated SSL object with its read and write BIOs set, in the same way as might be done for a call to SSL_accept(). Typically, for DTLS, the read BIO will be in an \"unconnected\" state and thus capable of receiving messages from any peer.

When a ClientHello is received that contains a cookie that has been verified, then these functions will return with the ssl parameter updated into a state where the handshake can be continued by a call to (for example) SSL_accept(). Additionally, for DTLSv1_listen(), the BIO_ADDR pointed to by peer will be filled in with details of the peer that sent the ClientHello. If the underlying BIO is unable to obtain the BIO_ADDR of the peer (for example because the BIO does not support this), then *peer will be cleared and the family set to AF_UNSPEC. Typically user code is expected to \"connect\" the underlying socket to the peer and continue the handshake in a connected state.

Warning: It is essential that the calling code connects the underlying socket to the peer after making use of DTLSv1_listen(). In the typical case where BIO_s_datagram(3) is used, the peer address is updated when receiving a datagram on an unconnected socket. If the socket is not connected, it can receive datagrams from any host on the network, which will cause subsequent outgoing datagrams transmitted by DTLS to be transmitted to that host. In other words, failing to call BIO_connect() or a similar OS-specific function on a socket means that any host on the network can cause outgoing DTLS traffic to be redirected to it by sending a datagram to the socket in question. This does not break the cryptographic protections of DTLS but may facilitate a denial-of-service attack or allow unencrypted information in the DTLS handshake to be learned by an attacker. This is due to the historical design of BIO_s_datagram(3); see BIO_s_datagram(3) for details on this issue.

Once a socket has been connected, BIO_ctrl_set_connected(3) should be used to inform the BIO that the socket is to be used in connected mode.

Prior to calling DTLSv1_listen() user code must ensure that cookie generation and verification callbacks have been set up using SSL_CTX_set_cookie_generate_cb(3) and SSL_CTX_set_cookie_verify_cb(3) respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb(3) and SSL_CTX_set_stateless_cookie_verify_cb(3) must be used instead.

Since DTLSv1_listen() operates entirely statelessly whilst processing incoming ClientHellos it is unable to process fragmented messages (since this would require the allocation of state). An implication of this is that DTLSv1_listen() only supports ClientHellos that fit inside a single datagram.

For SSL_stateless() if an entire ClientHello message cannot be read without the \"read\" BIO becoming empty then the SSL_stateless() call will fail. It is the application's responsibility to ensure that data read from the \"read\" BIO during a single SSL_stateless() call is all from the same peer.

SSL_stateless() will fail (with a 0 return value) if some TLS version less than TLSv1.3 is used.

Both SSL_stateless() and DTLSv1_listen() will clear the error queue when they start.

SSL_stateless() cannot be used with QUIC SSL objects and returns an error if called on such an object.

"},{"location":"man3/DTLSv1_listen/#return-values","title":"RETURN VALUES","text":"

For SSL_stateless() a return value of 1 indicates success and the ssl object will be set up ready to continue the handshake. A return value of 0 or -1 indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value of -1 indicates any other error. User code may retry the SSL_stateless() call.

For DTLSv1_listen() a return value of >= 1 indicates success. The ssl object will be set up ready to continue the handshake. the peer value will also be filled in.

A return value of 0 indicates a non-fatal error. This could (for example) be because of nonblocking IO, or some invalid message having been received from a peer. Errors may be placed on the OpenSSL error queue with further information if appropriate. Typically user code is expected to retry the call to DTLSv1_listen() in the event of a non-fatal error.

A return value of <0 indicates a fatal error. This could (for example) be because of a failure to allocate sufficient memory for the operation.

For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both produce return codes <= 0 (in typical implementations user code treats all errors as non-fatal), whilst return codes >0 indicate success.

"},{"location":"man3/DTLSv1_listen/#see-also","title":"SEE ALSO","text":"

SSL_CTX_set_cookie_generate_cb(3), SSL_CTX_set_cookie_verify_cb(3), SSL_CTX_set_stateless_cookie_generate_cb(3), SSL_CTX_set_stateless_cookie_verify_cb(3), SSL_get_error(3), SSL_accept(3), ssl(7), bio(7)

"},{"location":"man3/DTLSv1_listen/#history","title":"HISTORY","text":"

The SSL_stateless() function was added in OpenSSL 1.1.1.

The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of \"peer\" also changed in OpenSSL 1.1.0.

"},{"location":"man3/DTLSv1_listen/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2023 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.

"},{"location":"man3/ECDSA_SIG_new/","title":"ECDSA_SIG_new","text":""},{"location":"man3/ECDSA_SIG_new/#name","title":"NAME","text":"

ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0 - Functions for creating, destroying and manipulating ECDSA_SIG objects

"},{"location":"man3/ECDSA_SIG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ecdsa.h>\n\nECDSA_SIG *ECDSA_SIG_new(void);\nvoid ECDSA_SIG_free(ECDSA_SIG *sig);\nvoid ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);\nconst BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);\nconst BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);\nint ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);\n
"},{"location":"man3/ECDSA_SIG_new/#description","title":"DESCRIPTION","text":"

ECDSA_SIG is an opaque structure consisting of two BIGNUMs for the r and s value of an Elliptic Curve Digital Signature Algorithm (ECDSA) signature (see FIPS186-4 or X9.62). The ECDSA_SIG object was mainly used by the deprecated low level functions described in ECDSA_sign(3), it is still required in order to be able to set or get the values of r and s into or from a signature. This is mainly used for testing purposes as shown in the \"EXAMPLES\".

ECDSA_SIG_new() allocates an empty ECDSA_SIG structure. Note: before OpenSSL 1.1.0, the r and s components were initialised.

ECDSA_SIG_free() frees the ECDSA_SIG structure sig. If the argument is NULL, nothing is done.

ECDSA_SIG_get0() returns internal pointers the r and s values contained in sig and stores them in *pr and *ps, respectively. The pointer pr or ps can be NULL, in which case the corresponding value is not returned.

The values r, s can also be retrieved separately by the corresponding function ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s(), respectively.

Non-NULL r and s values can be set on the sig by calling ECDSA_SIG_set0(). Calling this function transfers the memory management of the values to the ECDSA_SIG object, and therefore the values that have been passed in should not be freed by the caller.

See i2d_ECDSA_SIG(3) and d2i_ECDSA_SIG(3) for information about encoding and decoding ECDSA signatures to/from DER.

"},{"location":"man3/ECDSA_SIG_new/#return-values","title":"RETURN VALUES","text":"

ECDSA_SIG_new() returns NULL if the allocation fails.

ECDSA_SIG_set0() returns 1 on success or 0 on failure.

ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s() return the corresponding value, or NULL if it is unset.

"},{"location":"man3/ECDSA_SIG_new/#examples","title":"EXAMPLES","text":"

Extract signature r and s values from a ECDSA signature of size signaturelen:

ECDSA_SIG *obj;\nconst BIGNUM *r, *s;\n\n/* Load a signature into the ECDSA_SIG object */\nobj = d2i_ECDSA_SIG(NULL, &signature, signaturelen);\nif (obj == NULL)\n    /* error */\n\nr = ECDSA_SIG_get0_r(obj);\ns = ECDSA_SIG_get0_s(obj);\nif (r == NULL || s == NULL)\n    /* error */\n\n/* Use BN_bn2binpad() here to convert to r and s into byte arrays */\n\n/*\n * Do not try to access I<r> or I<s> after calling ECDSA_SIG_free(),\n * as they are both freed by this call.\n */\nECDSA_SIG_free(obj);\n

Convert r and s byte arrays into an ECDSA_SIG signature of size signaturelen:

ECDSA_SIG *obj = NULL;\nunsigned char *signature = NULL;\nsize_t signaturelen;\nBIGNUM *rbn = NULL, *sbn = NULL;\n\nobj = ECDSA_SIG_new();\nif (obj == NULL)\n    /* error */\nrbn = BN_bin2bn(r, rlen, NULL);\nsbn = BN_bin2bn(s, slen, NULL);\nif (rbn == NULL || sbn == NULL)\n    /* error */\n\nif (!ECDSA_SIG_set0(obj, rbn, sbn))\n    /* error */\n/* Set these to NULL since they are now owned by obj */\nrbn = sbn = NULL;\n\nsignaturelen = i2d_ECDSA_SIG(obj, &signature);\nif (signaturelen <= 0)\n    /* error */\n\n/*\n * This signature could now be passed to L<EVP_DigestVerify(3)>\n * or L<EVP_DigestVerifyFinal(3)>\n */\n\nBN_free(rbn);\nBN_free(sbn);\nOPENSSL_free(signature);\nECDSA_SIG_free(obj);\n
"},{"location":"man3/ECDSA_SIG_new/#conforming-to","title":"CONFORMING TO","text":"

ANSI X9.62, US Federal Information Processing Standard FIPS186-4 (Digital Signature Standard, DSS)

"},{"location":"man3/ECDSA_SIG_new/#see-also","title":"SEE ALSO","text":"

EC_KEY_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_sign(3) i2d_ECDSA_SIG(3), d2i_ECDSA_SIG(3), ECDSA_sign(3)

"},{"location":"man3/ECDSA_SIG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2024 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.

"},{"location":"man3/ECDSA_sign/","title":"ECDSA_sign","text":""},{"location":"man3/ECDSA_sign/#name","title":"NAME","text":"

ECDSA_size, ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex, ECDSA_do_sign_ex - deprecated low-level elliptic curve digital signature algorithm (ECDSA) functions

"},{"location":"man3/ECDSA_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ecdsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int ECDSA_size(const EC_KEY *eckey);\n\nint ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,\n               unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);\nECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,\n                         EC_KEY *eckey);\n\nint ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,\n                 const unsigned char *sig, int siglen, EC_KEY *eckey);\nint ECDSA_do_verify(const unsigned char *dgst, int dgst_len,\n                    const ECDSA_SIG *sig, EC_KEY* eckey);\n\nECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,\n                            const BIGNUM *kinv, const BIGNUM *rp,\n                            EC_KEY *eckey);\nint ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);\nint ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,\n                  unsigned char *sig, unsigned int *siglen,\n                  const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);\n
"},{"location":"man3/ECDSA_sign/#description","title":"DESCRIPTION","text":"

See ECDSA_SIG_new(3) for a description of the ECDSA_SIG object.

See i2d_ECDSA_SIG(3) and d2i_ECDSA_SIG(3) for information about encoding and decoding ECDSA signatures to/from DER.

All of the functions described below are deprecated. Applications should use the higher level EVP interface such as EVP_DigestSignInit(3) or EVP_DigestVerifyInit(3) instead.

ECDSA_size() returns the maximum length of a DER encoded ECDSA signature created with the private EC key eckey. To obtain the actual signature size use EVP_PKEY_sign(3) with a NULL sig parameter.

ECDSA_sign() computes a digital signature of the dgstlen bytes hash value dgst using the private EC key eckey. The DER encoded signatures is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with kinv and rp set to NULL.

ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned as a newly allocated ECDSA_SIG structure (or NULL on error). ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with kinv and rp set to NULL.

ECDSA_verify() verifies that the signature in sig of size siglen is a valid ECDSA signature of the hash value dgst of size dgstlen using the public key eckey. The parameter type is ignored.

ECDSA_do_verify() is similar to ECDSA_verify() except the signature is presented in the form of a pointer to an ECDSA_SIG structure.

The remaining functions utilise the internal kinv and r values used during signature computation. Most applications will never need to call these and some external ECDSA ENGINE implementations may not support them at all if either kinv or r is not NULL.

ECDSA_sign_setup() may be used to precompute parts of the signing operation. eckey is the private EC key and ctx is a pointer to BN_CTX structure (or NULL). The precomputed values or returned in kinv and rp and can be used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().

ECDSA_sign_ex() computes a digital signature of the dgstlen bytes hash value dgst using the private EC key eckey and the optional pre-computed values kinv and rp. The DER encoded signature is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is ignored.

ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is returned as a newly allocated ECDSA_SIG structure (or NULL on error).

"},{"location":"man3/ECDSA_sign/#return-values","title":"RETURN VALUES","text":"

ECDSA_size() returns the maximum length signature or 0 on error.

ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful or 0 on error.

ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated ECDSA_SIG structure or NULL on error.

ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0 for an invalid signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/ECDSA_sign/#examples","title":"EXAMPLES","text":"

Creating an ECDSA signature of a given SHA-256 hash value using the named curve prime256v1 (aka P-256). This example uses deprecated functionality. See \"DESCRIPTION\".

First step: create an EC_KEY object (note: this part is not ECDSA specific)

int ret;\nECDSA_SIG *sig;\nEC_KEY *eckey;\n\neckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);\nif (eckey == NULL)\n    /* error */\nif (EC_KEY_generate_key(eckey) == 0)\n    /* error */\n

Second step: compute the ECDSA signature of a SHA-256 hash value using ECDSA_do_sign():

sig = ECDSA_do_sign(digest, 32, eckey);\nif (sig == NULL)\n    /* error */\n

or using ECDSA_sign():

unsigned char *buffer, *pp;\nint buf_len;\n\nbuf_len = ECDSA_size(eckey);\nbuffer = OPENSSL_malloc(buf_len);\npp = buffer;\nif (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)\n    /* error */\n

Third step: verify the created ECDSA signature using ECDSA_do_verify():

ret = ECDSA_do_verify(digest, 32, sig, eckey);\n

or using ECDSA_verify():

ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);\n

and finally evaluate the return value:

if (ret == 1)\n    /* signature ok */\nelse if (ret == 0)\n    /* incorrect signature */\nelse\n    /* error */\n
"},{"location":"man3/ECDSA_sign/#conforming-to","title":"CONFORMING TO","text":"

ANSI X9.62, US Federal Information Processing Standard FIPS186-2 (Digital Signature Standard, DSS)

"},{"location":"man3/ECDSA_sign/#see-also","title":"SEE ALSO","text":"

EC_KEY_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_sign(3) i2d_ECDSA_SIG(3), d2i_ECDSA_SIG(3)

"},{"location":"man3/ECDSA_sign/#history","title":"HISTORY","text":"

All functionality described here was deprecated in OpenSSL 3.0.

"},{"location":"man3/ECDSA_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2022 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.

"},{"location":"man3/ECPKParameters_print/","title":"ECPKParameters_print","text":""},{"location":"man3/ECPKParameters_print/#name","title":"NAME","text":"

ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities

"},{"location":"man3/ECPKParameters_print/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);\nint ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);\n
"},{"location":"man3/ECPKParameters_print/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_print_params(3)

The ECPKParameters represent the public parameters for an EC_GROUP structure, which represents a curve.

The ECPKParameters_print() and ECPKParameters_print_fp() functions print a human-readable output of the public parameters of the EC_GROUP to bp or fp. The output lines are indented by off spaces.

"},{"location":"man3/ECPKParameters_print/#return-values","title":"RETURN VALUES","text":"

ECPKParameters_print() and ECPKParameters_print_fp() return 1 for success and 0 if an error occurs.

"},{"location":"man3/ECPKParameters_print/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3),

"},{"location":"man3/ECPKParameters_print/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/ECPKParameters_print/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2021 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.

"},{"location":"man3/EC_GFp_simple_method/","title":"EC_GFp_simple_method","text":""},{"location":"man3/EC_GFp_simple_method/#name","title":"NAME","text":"

EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects

"},{"location":"man3/EC_GFp_simple_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_GFp_simple_method(void);\nconst EC_METHOD *EC_GFp_mont_method(void);\nconst EC_METHOD *EC_GFp_nist_method(void);\nconst EC_METHOD *EC_GFp_nistp224_method(void);\nconst EC_METHOD *EC_GFp_nistp256_method(void);\nconst EC_METHOD *EC_GFp_nistp521_method(void);\n\nconst EC_METHOD *EC_GF2m_simple_method(void);\n\nint EC_METHOD_get_field_type(const EC_METHOD *meth);\n
"},{"location":"man3/EC_GFp_simple_method/#description","title":"DESCRIPTION","text":"

All const EC_METHOD *EC_GF* functions were deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

The Elliptic Curve library provides a number of different implementations through a single common interface. When constructing a curve using EC_GROUP_new (see EC_GROUP_new(3)) an implementation method must be provided. The functions described here all return a const pointer to an EC_METHOD structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation type for the form of curve selected is used.

For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.

For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the use of montgomery multiplication (see BN_mod_mul_montgomery(3)). EC_GFp_nist_method offers an implementation optimised for use with NIST recommended curves (NIST curves are available through EC_GROUP_new_by_curve_name as described in EC_GROUP_new(3)).

The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these implementations are not available on all platforms.

EC_METHOD_get_field_type() was deprecated in OpenSSL 3.0. Applications should use EC_GROUP_get_field_type() as a replacement (see EC_GROUP_copy(3)).

"},{"location":"man3/EC_GFp_simple_method/#return-values","title":"RETURN VALUES","text":"

All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.

EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.

"},{"location":"man3/EC_GFp_simple_method/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), d2i_ECPKParameters(3), BN_mod_mul_montgomery(3)

"},{"location":"man3/EC_GFp_simple_method/#history","title":"HISTORY","text":"

EC_GFp_simple_method(), EC_GFp_mont_method(void), EC_GFp_nist_method(), EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(), EC_GF2m_simple_method(), and EC_METHOD_get_field_type() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EC_GFp_simple_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EC_GROUP_copy/","title":"EC_GROUP_copy","text":""},{"location":"man3/EC_GROUP_copy/#name","title":"NAME","text":"

EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_named_curve, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field, EC_GROUP_get_field_type - Functions for manipulating EC_GROUP objects

"},{"location":"man3/EC_GROUP_copy/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nint EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);\nEC_GROUP *EC_GROUP_dup(const EC_GROUP *src);\n\nint EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator,\n                           const BIGNUM *order, const BIGNUM *cofactor);\nconst EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);\n\nint EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);\nconst BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);\nint EC_GROUP_order_bits(const EC_GROUP *group);\nint EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);\nconst BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);\nconst BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group);\n\nvoid EC_GROUP_set_curve_name(EC_GROUP *group, int nid);\nint EC_GROUP_get_curve_name(const EC_GROUP *group);\n\nvoid EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);\nint EC_GROUP_get_asn1_flag(const EC_GROUP *group);\n\nvoid EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);\npoint_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group);\n\nunsigned char *EC_GROUP_get0_seed(const EC_GROUP *group);\nsize_t EC_GROUP_get_seed_len(const EC_GROUP *group);\nsize_t EC_GROUP_set_seed(EC_GROUP *group, const unsigned char *, size_t len);\n\nint EC_GROUP_get_degree(const EC_GROUP *group);\n\nint EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);\nint EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only,\n                               BN_CTX *ctx);\n\nint EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);\n\nint EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);\n\nint EC_GROUP_get_basis_type(const EC_GROUP *group);\nint EC_GROUP_get_trinomial_basis(const EC_GROUP *group, unsigned int *k);\nint EC_GROUP_get_pentanomial_basis(const EC_GROUP *group, unsigned int *k1,\n                                   unsigned int *k2, unsigned int *k3);\n\nint EC_GROUP_get_field_type(const EC_GROUP *group);\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);\n
"},{"location":"man3/EC_GROUP_copy/#description","title":"DESCRIPTION","text":"

EC_GROUP_copy() copies the curve src into dst. Both src and dst must use the same EC_METHOD.

EC_GROUP_dup() creates a new EC_GROUP object and copies the content from src to the newly created EC_GROUP object.

EC_GROUP_method_of() obtains the EC_METHOD of group. This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These parameters include the generator, the order and the cofactor. The generator is a well defined point on the curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and n-1 where n is the order. The order multiplied by the cofactor gives the number of points on the curve.

EC_GROUP_get0_generator() returns the generator for the identified group.

EC_GROUP_get_order() retrieves the order of group and copies its value into order. It fails in case group is not fully initialized (i.e., its order is not set or set to zero).

EC_GROUP_get_cofactor() retrieves the cofactor of group and copies its value into cofactor. It fails in case group is not fully initialized or if the cofactor is not set (or set to zero).

The functions EC_GROUP_set_curve_name() and EC_GROUP_get_curve_name(), set and get the NID for the curve respectively (see EC_GROUP_new(3)). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name will return NID_undef.

The asn1_flag value is used to determine whether the curve encoding uses explicit parameters or a named curve using an ASN1 OID: many applications only support the latter form. If asn1_flag is OPENSSL_EC_NAMED_CURVE then the named curve form is used and the parameters must have a corresponding named curve NID set. If asn1_flags is OPENSSL_EC_EXPLICIT_CURVE the parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag() and EC_GROUP_set_asn1_flag() get and set the status of the asn1_flag for the curve. Note: OPENSSL_EC_EXPLICIT_CURVE was added in OpenSSL 1.1.0, for previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL 1.1.0 the default form was to use explicit parameters (meaning that applications would have to explicitly set the named curve form) in OpenSSL 1.1.0 and later the named curve form is the default.

The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). point_conversion_form_t is an enum defined as follows:

typedef enum {\n       /** the point is encoded as z||x, where the octet z specifies\n        *   which solution of the quadratic equation y is  */\n       POINT_CONVERSION_COMPRESSED = 2,\n       /** the point is encoded as z||x||y, where z is the octet 0x04  */\n       POINT_CONVERSION_UNCOMPRESSED = 4,\n       /** the point is encoded as z||x||y, where the octet z specifies\n        *  which solution of the quadratic equation y is  */\n       POINT_CONVERSION_HYBRID = 6\n} point_conversion_form_t;\n

For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by the octets for x, followed by the octets for y.

For any given x coordinate for a point on a curve it is possible to derive two possible y values. For POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of the two possible solutions for y has been used, followed by the octets for x.

For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two possible solutions for y has been used, followed by the octets for x, followed by the octets for y.

The functions EC_GROUP_set_point_conversion_form() and EC_GROUP_get_point_conversion_form(), set and get the point_conversion_form for the curve respectively.

ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed(). This returns a pointer to a memory block containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len(). A number of the built-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use this seed value, although it will be preserved in any ASN1 based communications.

EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be the value m.

EC_GROUP_get_field_type() identifies what type of field the EC_GROUP structure supports, which will be either F2^m or Fp.

The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid. For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b. In either case for the curve to be valid the discriminant must be non zero.

The function EC_GROUP_check() behaves in the following way: For the OpenSSL default provider it performs a number of checks on a curve to verify that it is valid. Checks performed include verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has the correct order. For the OpenSSL FIPS provider it uses EC_GROUP_check_named_curve() to conform to SP800-56Ar3.

The function EC_GROUP_check_named_curve() determines if the group's domain parameters match one of the built-in curves supported by the library. The curve name is returned as a NID if it matches. If the group's domain parameters have been modified then no match will be found. If the curve name of the given group is NID_undef (e.g. it has been created by using explicit parameters with no curve name), then this method can be used to lookup the name of the curve that matches the group domain parameters. The built-in curves contain aliases, so that multiple NID's can map to the same domain parameters. For such curves it is unspecified which of the aliases will be returned if the curve name of the given group is NID_undef. If nist_only is 1 it will only look for NIST approved curves, otherwise it searches all built-in curves. This function may be passed a BN_CTX object in the ctx parameter. The ctx parameter may be NULL.

EC_GROUP_cmp() compares a and b to determine whether they represent the same curve or not.

The functions EC_GROUP_get_basis_type(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis() should only be called for curves defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial function f(x). This function is either a trinomial of the form:

f(x) = x^m + x^k + 1 with m > k >= 1

or a pentanomial of the form:

f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1

The function EC_GROUP_get_basis_type() returns a NID identifying whether a trinomial or pentanomial is in use for the field. The function EC_GROUP_get_trinomial_basis() must only be called where f(x) is of the trinomial form, and returns the value of k. Similarly the function EC_GROUP_get_pentanomial_basis() must only be called where f(x) is of the pentanomial form, and returns the values of k1, k2 and k3 respectively.

"},{"location":"man3/EC_GROUP_copy/#return-values","title":"RETURN VALUES","text":"

The following functions return 1 on success or 0 on error: EC_GROUP_copy(), EC_GROUP_set_generator(), EC_GROUP_check(), EC_GROUP_check_discriminant(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis().

EC_GROUP_dup() returns a pointer to the duplicated curve, or NULL on error.

EC_GROUP_method_of() returns the EC_METHOD implementation in use for the given curve or NULL on error.

EC_GROUP_get0_generator() returns the generator for the given curve or NULL on error.

EC_GROUP_get_order() returns 0 if the order is not set (or set to zero) for group or if copying into order fails, 1 otherwise.

EC_GROUP_get_cofactor() returns 0 if the cofactor is not set (or is set to zero) for group or if copying into cofactor fails, 1 otherwise.

EC_GROUP_get_curve_name() returns the curve name (NID) for group or will return NID_undef if no curve name is associated.

EC_GROUP_get_asn1_flag() returns the ASN1 flag for the specified group .

EC_GROUP_get_point_conversion_form() returns the point_conversion_form for group.

EC_GROUP_get_degree() returns the degree for group or 0 if the operation is not supported by the underlying group implementation.

EC_GROUP_get_field_type() returns either NID_X9_62_prime_field for prime curves or NID_X9_62_characteristic_two_field for binary curves; these values are defined in the <openssl/obj_mac.h> header file.

EC_GROUP_check_named_curve() returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.

EC_GROUP_get0_order() returns an internal pointer to the group order. EC_GROUP_order_bits() returns the number of bits in the group order. EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor. EC_GROUP_get0_field() returns an internal pointer to the group field. For curves over GF(p), this is the modulus; for curves over GF(2^m), this is the irreducible polynomial defining the field.

EC_GROUP_get0_seed() returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not specified. EC_GROUP_get_seed_len() returns the length of the seed or 0 if the seed is not specified.

EC_GROUP_set_seed() returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is 0, the return value will be 1. On error 0 is returned.

EC_GROUP_cmp() returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.

EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.

"},{"location":"man3/EC_GROUP_copy/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_GROUP_copy/#history","title":"HISTORY","text":"

EC_GROUP_method_of() was deprecated in OpenSSL 3.0. EC_GROUP_get0_field(), EC_GROUP_check_named_curve() and EC_GROUP_get_field_type() were added in OpenSSL 3.0. EC_GROUP_get0_order(), EC_GROUP_order_bits() and EC_GROUP_get0_cofactor() were added in OpenSSL 1.1.0.

"},{"location":"man3/EC_GROUP_copy/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 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.

"},{"location":"man3/EC_GROUP_new/","title":"EC_GROUP_new","text":""},{"location":"man3/EC_GROUP_new/#name","title":"NAME","text":"

EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, EC_GROUP_new_from_params, EC_GROUP_to_params, EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name_ex, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves, OSSL_EC_curve_nid2name - Functions for creating and destroying EC_GROUP objects

"},{"location":"man3/EC_GROUP_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[],\n                                   OSSL_LIB_CTX *libctx, const char *propq);\nOSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx,\n                               const char *propq, BN_CTX *bnctx);\nEC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params);\nEC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params);\nvoid EC_GROUP_free(EC_GROUP *group);\n\nEC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,\n                                 const BIGNUM *b, BN_CTX *ctx);\nEC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,\n                                  const BIGNUM *b, BN_CTX *ctx);\nEC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq,\n                                        int nid);\nEC_GROUP *EC_GROUP_new_by_curve_name(int nid);\n\nint EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,\n                       const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,\n                       BN_CTX *ctx);\n\nECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group,\n                                        ECPARAMETERS *params);\nECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group,\n                                            ECPKPARAMETERS *params);\n\nsize_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);\nconst char *OSSL_EC_curve_nid2name(int nid);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);\nvoid EC_GROUP_clear_free(EC_GROUP *group);\n\nint EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,\n                           const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,\n                           BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,\n                            const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,\n                            BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/EC_GROUP_new/#description","title":"DESCRIPTION","text":"

Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised elliptic curve equation as follows:

y^2 mod p = x^3 +ax + b mod p

The second form is those defined over a binary field F2^m where the elements of the field are integers of length at most m bits. For this form the elliptic curve equation is modified to:

y^2 + xy = x^3 + ax^2 + b (where b != 0)

Operations in a binary field are performed relative to an irreducible polynomial. All such curves with OpenSSL use a trinomial or a pentanomial for this parameter.

Although deprecated since OpenSSL 3.0 and should no longer be used, a new curve can be constructed by calling EC_GROUP_new(), using the implementation provided by meth (see EC_GFp_simple_method(3)) and associated with the library context ctx (see OSSL_LIB_CTX(3)). The ctx parameter may be NULL in which case the default library context is used. It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. Applications should instead use one of the other EC_GROUP_new_* constructors.

EC_GROUP_new_from_params() creates a group with parameters specified by params. The library context libctx (see OSSL_LIB_CTX(3)) and property query string propq are used to fetch algorithms from providers. params may be either a list of explicit params or a named group, The values for ctx and propq may be NULL. The params that can be used are described in EVP_PKEY-EC(7).

EC_GROUP_to_params creates an OSSL_PARAM array with the corresponding parameters describing the given EC_GROUP. The resulting parameters may contain parameters describing a named or explicit curve depending on the EC_GROUP. The library context libctx (see OSSL_LIB_CTX(3)) and property query string propq are used to fetch algorithms from providers. bnctx is an optional preallocated BN_CTX (to save the overhead of allocating and freeing the structure in a loop). The values for libctx, propq and bnctx may be NULL. The caller is responsible for freeing the OSSL_PARAM pointer returned.

EC_GROUP_new_from_ecparameters() will create a group from the specified params and EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK params.

EC_GROUP_set_curve() sets the curve parameters p, a and b. For a curve over Fp p is the prime for the field. For a curve over F2^m p represents the irreducible polynomial - each bit represents a term in the polynomial. Therefore, there will either be three or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. In either case, a and b represents the coefficients a and b from the relevant equation introduced above.

EC_group_get_curve() obtains the previously set curve parameters.

EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for backwards compatibility only and should not be used.

EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for backwards compatibility only and should not be used.

The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function. An appropriate default implementation method will be used.

Whilst the library can be used to create any curve using the functions described above, there are also a number of predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function EC_get_builtin_curves(). The parameter r should be an array of EC_builtin_curve structures of size nitems. The function will populate the r array with information about the built-in curves. If nitems is less than the total number of curves available, then the first nitems curves will be returned. Otherwise the total number of curves will be provided. The return value is the total number of curves available (whether that number has been populated in r or not). Passing a NULL r, or setting nitems to 0 will do nothing other than return the total number of curves available. The EC_builtin_curve structure is defined as follows:

typedef struct {\n       int nid;\n       const char *comment;\n       } EC_builtin_curve;\n

Each EC_builtin_curve item has a unique integer id (nid), and a human readable comment string describing the curve.

In order to construct a built-in curve use the function EC_GROUP_new_by_curve_name_ex() and provide the nid of the curve to be constructed, the associated library context to be used in ctx (see OSSL_LIB_CTX(3)) and any property query string in propq. The ctx value may be NULL in which case the default library context is used. The propq value may also be NULL.

EC_GROUP_new_by_curve_name() is the same as EC_GROUP_new_by_curve_name_ex() except that the default library context is always used along with a NULL property query string.

EC_GROUP_free() frees the memory associated with the EC_GROUP. If group is NULL nothing is done.

EC_GROUP_clear_free() is deprecated: it was meant to destroy any sensitive data held within the EC_GROUP and then free its memory, but since all the data stored in the EC_GROUP is public anyway, this function is unnecessary. Its use can be safely replaced with EC_GROUP_free(). If group is NULL nothing is done.

OSSL_EC_curve_nid2name() converts a curve nid into the corresponding name.

"},{"location":"man3/EC_GROUP_new/#return-values","title":"RETURN VALUES","text":"

All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.

EC_get_builtin_curves() returns the number of built-in curves that are available.

EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.

OSSL_EC_curve_nid2name() returns a character string constant, or NULL on error.

"},{"location":"man3/EC_GROUP_new/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), OSSL_LIB_CTX(3), EVP_PKEY-EC(7)

"},{"location":"man3/EC_GROUP_new/#history","title":"HISTORY","text":""},{"location":"man3/EC_GROUP_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 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.

"},{"location":"man3/EC_KEY_get_enc_flags/","title":"EC_KEY_get_enc_flags","text":""},{"location":"man3/EC_KEY_get_enc_flags/#name","title":"NAME","text":"

EC_KEY_get_enc_flags, EC_KEY_set_enc_flags - Get and set flags for encoding EC_KEY structures

"},{"location":"man3/EC_KEY_get_enc_flags/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nunsigned int EC_KEY_get_enc_flags(const EC_KEY *key);\nvoid EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);\n
"},{"location":"man3/EC_KEY_get_enc_flags/#description","title":"DESCRIPTION","text":"

The format of the external representation of the public key written by i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is described by the point_conversion_form. See EC_GROUP_copy(3) for a description of point_conversion_form.

When reading a private key encoded without an associated public key (e.g. if EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates the missing public key automatically. Private keys encoded without parameters (e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using d2i_ECPrivateKey().

The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the value of the encoding flags for the key. There are two encoding flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the key is converted into ASN1 in a call to i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key.

"},{"location":"man3/EC_KEY_get_enc_flags/#return-values","title":"RETURN VALUES","text":"

EC_KEY_get_enc_flags() returns the value of the current encoding flags for the EC_KEY.

"},{"location":"man3/EC_KEY_get_enc_flags/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), d2i_ECPrivateKey(3)

"},{"location":"man3/EC_KEY_get_enc_flags/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2017 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.

"},{"location":"man3/EC_KEY_new/","title":"EC_KEY_new","text":""},{"location":"man3/EC_KEY_new/#name","title":"NAME","text":"

EVP_EC_gen, EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex, EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_decoded_from_explicit_params, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, EC_KEY_priv2buf - Functions for creating, destroying and manipulating EC_KEY objects

"},{"location":"man3/EC_KEY_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEVP_PKEY *EVP_EC_gen(const char *curve);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EC_KEY *EC_KEY_new_ex(OSSL_LIB_CTX *ctx, const char *propq);\nEC_KEY *EC_KEY_new(void);\nint EC_KEY_get_flags(const EC_KEY *key);\nvoid EC_KEY_set_flags(EC_KEY *key, int flags);\nvoid EC_KEY_clear_flags(EC_KEY *key, int flags);\nEC_KEY *EC_KEY_new_by_curve_name_ex(OSSL_LIB_CTX *ctx, const char *propq,\n                                    int nid);\nEC_KEY *EC_KEY_new_by_curve_name(int nid);\nvoid EC_KEY_free(EC_KEY *key);\nEC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);\nEC_KEY *EC_KEY_dup(const EC_KEY *src);\nint EC_KEY_up_ref(EC_KEY *key);\nENGINE *EC_KEY_get0_engine(const EC_KEY *eckey);\nconst EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);\nint EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);\nconst BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);\nint EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv_key);\nconst EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);\nint EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);\npoint_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);\nvoid EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);\nvoid EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);\nint EC_KEY_decoded_from_explicit_params(const EC_KEY *key);\nint EC_KEY_generate_key(EC_KEY *key);\nint EC_KEY_check_key(const EC_KEY *key);\nint EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);\nconst EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);\nint EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);\n\nint EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, BN_CTX *ctx);\nsize_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form,\n                      unsigned char **pbuf, BN_CTX *ctx);\n\nint EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len);\nsize_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len);\n\nsize_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);\nint EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);\n
"},{"location":"man3/EC_KEY_new/#description","title":"DESCRIPTION","text":"

EVP_EC_gen() generates a new EC key pair on the given curve.

All of the functions described below are deprecated. Applications should instead use EVP_EC_gen(), EVP_PKEY_Q_keygen(3), or EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3).

An EC_KEY represents a public key and, optionally, the associated private key. A new EC_KEY with no associated curve can be constructed by calling EC_KEY_new_ex() and specifying the associated library context in ctx (see OSSL_LIB_CTX(3)) and property query string propq. The ctx parameter may be NULL in which case the default library context is used. The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling EC_KEY_set_group().

EC_KEY_new() is the same as EC_KEY_new_ex() except that the default library context is always used.

Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name_ex() and supplying the nid of the associated curve, the library context to be used ctx (see OSSL_LIB_CTX(3)) and any property query string propq. The ctx parameter may be NULL in which case the default library context is used. The propq value may also be NULL. See EC_GROUP_new(3) for a description of curve names. This function simply wraps calls to EC_KEY_new_ex() and EC_GROUP_new_by_curve_name_ex().

EC_KEY_new_by_curve_name() is the same as EC_KEY_new_by_curve_name_ex() except that the default library context is always used and a NULL property query string.

Calling EC_KEY_free() decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated with it. If key is NULL nothing is done.

EC_KEY_copy() copies the contents of the EC_KEY in src into dest.

EC_KEY_dup() creates a new EC_KEY object and copies ec_key into it.

EC_KEY_up_ref() increments the reference count associated with the EC_KEY object.

EC_KEY_get0_engine() returns a handle to the ENGINE that has been set for this EC_KEY object.

EC_KEY_generate_key() generates a new public and private key for the supplied eckey object. eckey must have an EC_GROUP object associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the private key.

EC_KEY_check_key() performs various sanity checks on the EC_KEY object to confirm that it is valid.

EC_KEY_set_public_key_affine_coordinates() sets the public key for key based on its affine coordinates; i.e., it constructs an EC_POINT object based on the supplied x and y values and sets the public key to be this EC_POINT. It also performs certain sanity checks on the key to confirm that it is valid.

The functions EC_KEY_get0_group(), EC_KEY_set_group(), EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key, and the EC_POINT public key for the key respectively. The function EC_KEY_set_private_key() accepts NULL as the priv_key argument to securely clear the private key component from the EC_KEY.

The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the point_conversion_form for the key. For a description of point_conversion_forms please see EC_POINT_new(3).

EC_KEY_set_flags() sets the flags in the flags parameter on the EC_KEY object. Any flags that are already set are left set. The flags currently defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH. EC_KEY_get_flags() returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags() clears the flags indicated by the flags parameter; all other flags are left in their existing state.

EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to EC_GROUP_copy(3) for further information on the asn1_flag.

EC_KEY_decoded_from_explicit_params() returns 1 if the group of the key was decoded from data with explicitly encoded group parameters, -1 if the key is NULL or the group parameters are missing, and 0 otherwise.

EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also EC_POINT_add(3). Modern versions should instead switch to named curves which OpenSSL has hardcoded lookup tables for.

EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions EC_POINT_oct2point() and EC_POINT_point2buf() except they use the public key EC_POINT in eckey.

EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key component of eckey and octet form. The octet form consists of the content octets of the privateKey OCTET STRING in an ECPrivateKey ASN.1 structure.

The function EC_KEY_priv2oct() must be supplied with a buffer long enough to store the octet form. The return value provides the number of octets stored. Calling the function with a NULL buffer will not perform the conversion but will just return the required buffer length.

The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes an EC_KEY to it in octet format. The allocated buffer is written to *pbuf and its length is returned. The caller must free up the allocated buffer with a call to OPENSSL_free(). Since the allocated buffer value is written to *pbuf the pbuf parameter MUST NOT be NULL.

EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.

"},{"location":"man3/EC_KEY_new/#return-values","title":"RETURN VALUES","text":"

EC_KEY_new_ex(), EC_KEY_new(), EC_KEY_new_by_curve_name_ex(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to the newly created EC_KEY object, or NULL on error.

EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an integer.

EC_KEY_copy() returns a pointer to the destination key, or NULL on error.

EC_KEY_get0_engine() returns a pointer to an ENGINE, or NULL if it wasn't set.

EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(), EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error.

EC_KEY_set_private_key() returns 1 on success or 0 on error except when the priv_key argument is NULL, in that case it returns 0, for legacy compatibility, and should not be treated as an error.

EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY.

EC_KEY_get0_private_key() returns the private key associated with the EC_KEY.

EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY.

EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length of the buffer or 0 on error.

"},{"location":"man3/EC_KEY_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_Q_keygen(3) crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), OSSL_LIB_CTX(3)

"},{"location":"man3/EC_KEY_new/#history","title":"HISTORY","text":"

EVP_EC_gen() was added in OpenSSL 3.0. All other functions described here were deprecated in OpenSSL 3.0. For replacement see EVP_PKEY-EC(7).

"},{"location":"man3/EC_KEY_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 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.

"},{"location":"man3/EC_POINT_add/","title":"EC_POINT_add","text":""},{"location":"man3/EC_POINT_add/#name","title":"NAME","text":"

EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects

"},{"location":"man3/EC_POINT_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nint EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a,\n                 const EC_POINT *b, BN_CTX *ctx);\nint EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);\nint EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);\nint EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);\nint EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);\nint EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);\nint EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,\n                 const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);\nint EC_POINTs_make_affine(const EC_GROUP *group, size_t num,\n                          EC_POINT *points[], BN_CTX *ctx);\nint EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,\n                  const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);\nint EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);\nint EC_GROUP_have_precompute_mult(const EC_GROUP *group);\n
"},{"location":"man3/EC_POINT_add/#description","title":"DESCRIPTION","text":"

EC_POINT_add adds the two points a and b and places the result in r. Similarly EC_POINT_dbl doubles the point a and places the result in r. In both cases it is valid for r to be one of a or b.

EC_POINT_invert calculates the inverse of the supplied point a. The result is placed back in a.

The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.

EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.

EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.

The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine coordinate system. In the case of EC_POINTs_make_affine the value num provides the number of points in the array points to be forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used. Modern versions automatically perform this conversion when needed.

EC_POINT_mul calculates the value generator * n + q * m and stores the result in r. The value n may be NULL in which case the result is just q * m (variable point multiplication). Alternatively, both q and m may be NULL, and n non-NULL, in which case the result is just generator * n (fixed point multiplication). When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either n or m) is in the range [0, ec_group_order).

Although deprecated in OpenSSL 3.0 and should no longer be used, EC_POINTs_mul calculates the value generator * n + q[0] * m[0] + ... + q[num-1] * m[num-1]. As for EC_POINT_mul the value n may be NULL or num may be zero. When performing a fixed point multiplication (n is non-NULL and num is 0) or a variable point multiplication (n is NULL and num is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either n or m[0]) is in the range [0, ec_group_order). Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_POINT_add() in such rare circumstances.

The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See EC_GROUP_copy(3) for information about the generator. Precomputation functionality was deprecated in OpenSSL 3.0. Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should switch to named curves which OpenSSL has hardcoded lookup tables for.

"},{"location":"man3/EC_POINT_add/#return-values","title":"RETURN VALUES","text":"

The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.

EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.

EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.

EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.

EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.

"},{"location":"man3/EC_POINT_add/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_POINT_add/#history","title":"HISTORY","text":"

EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(), EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EC_POINT_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 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.

"},{"location":"man3/EC_POINT_new/","title":"EC_POINT_new","text":""},{"location":"man3/EC_POINT_new/#name","title":"NAME","text":"

EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, EC_POINT_set_compressed_coordinates, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating EC_POINT objects

"},{"location":"man3/EC_POINT_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEC_POINT *EC_POINT_new(const EC_GROUP *group);\nvoid EC_POINT_free(EC_POINT *point);\nvoid EC_POINT_clear_free(EC_POINT *point);\nint EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);\nEC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);\nint EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);\nint EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,\n                                    const BIGNUM *x, const BIGNUM *y,\n                                    BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,\n                                    BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,\n                                        const BIGNUM *x, int y_bit,\n                                        BN_CTX *ctx);\nsize_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,\n                          point_conversion_form_t form,\n                          unsigned char *buf, size_t len, BN_CTX *ctx);\nsize_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,\n                          point_conversion_form_t form,\n                          unsigned char **pbuf, BN_CTX *ctx);\nint EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,\n                       const unsigned char *buf, size_t len, BN_CTX *ctx);\nchar *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,\n                         point_conversion_form_t form, BN_CTX *ctx);\nEC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,\n                             EC_POINT *p, BN_CTX *ctx);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);\nint EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,\n                                             EC_POINT *p,\n                                             const BIGNUM *x, const BIGNUM *y,\n                                             const BIGNUM *z, BN_CTX *ctx);\nint EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,\n                                             const EC_POINT *p,\n                                             BIGNUM *x, BIGNUM *y, BIGNUM *z,\n                                             BN_CTX *ctx);\nint EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,\n                                        const BIGNUM *x, const BIGNUM *y,\n                                        BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,\n                                        const EC_POINT *p,\n                                        BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,\n                                            EC_POINT *p,\n                                            const BIGNUM *x, int y_bit,\n                                            BN_CTX *ctx);\nint EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,\n                                         const BIGNUM *x, const BIGNUM *y,\n                                         BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,\n                                         const EC_POINT *p,\n                                         BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,\n                                             EC_POINT *p,\n                                             const BIGNUM *x, int y_bit,\n                                             BN_CTX *ctx);\nBIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,\n                          point_conversion_form_t form, BIGNUM *bn,\n                          BN_CTX *ctx);\nEC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,\n                            EC_POINT *p, BN_CTX *ctx);\n
"},{"location":"man3/EC_POINT_new/#description","title":"DESCRIPTION","text":"

An EC_POINT structure represents a point on a curve. A new point is constructed by calling the function EC_POINT_new() and providing the group object that the point relates to.

EC_POINT_free() frees the memory associated with the EC_POINT. if point is NULL nothing is done.

EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and then frees its memory. If point is NULL nothing is done.

EC_POINT_copy() copies the point src into dst. Both src and dst must use the same EC_METHOD.

EC_POINT_dup() creates a new EC_POINT object and copies the content from src to the newly created EC_POINT object.

EC_POINT_method_of() obtains the EC_METHOD associated with point. This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity().

The affine coordinates for a point describe a point in terms of its x and y position. The function EC_POINT_set_affine_coordinates() sets the x and y coordinates for the point p defined over the curve given in group. The function EC_POINT_get_affine_coordinates() sets x and y, either of which may be NULL, to the corresponding coordinates of p.

The functions EC_POINT_set_affine_coordinates_GFp() and EC_POINT_set_affine_coordinates_GF2m() are synonyms for EC_POINT_set_affine_coordinates(). They are defined for backwards compatibility only and should not be used.

The functions EC_POINT_get_affine_coordinates_GFp() and EC_POINT_get_affine_coordinates_GF2m() are synonyms for EC_POINT_get_affine_coordinates(). They are defined for backwards compatibility only and should not be used.

As well as the affine coordinates, a point can alternatively be described in terms of its Jacobian projective coordinates (for Fp curves only). Jacobian projective coordinates are expressed as three values x, y and z. Working in this coordinate system provides more efficient point multiplication operations. A mapping exists between Jacobian projective coordinates and affine coordinates. A Jacobian projective coordinate (x, y, z) can be written as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective from affine coordinates is simple. The coordinate (x, y) is mapped to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used, to set or get the projective coordinates in older versions use EC_POINT_set_Jprojective_coordinates_GFp() and EC_POINT_get_Jprojective_coordinates_GFp() respectively. Modern versions should instead use EC_POINT_set_affine_coordinates() and EC_POINT_get_affine_coordinates(), performing the conversion manually using the above maps in such rare circumstances.

Points can also be described in terms of their compressed coordinates. For a point (x, y), for any given value for x such that the point is on the curve there will only ever be two possible values for y. Therefore, a point can be set using the EC_POINT_set_compressed_coordinates() function where x is the x coordinate and y_bit is a value 0 or 1 to identify which of the two possible values for y should be used.

The functions EC_POINT_set_compressed_coordinates_GFp() and EC_POINT_set_compressed_coordinates_GF2m() are synonyms for EC_POINT_set_compressed_coordinates(). They are defined for backwards compatibility only and should not be used.

In addition EC_POINT can be converted to and from various external representations. The octet form is the binary encoding of the ECPoint structure (as defined in RFC5480 and used in certificates and TLS records): only the content octets are present, the OCTET STRING tag and length are not included. BIGNUM form is the octet form interpreted as a big endian integer converted to a BIGNUM structure. Hexadecimal form is the octet form converted to a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f).

The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.

The function EC_POINT_point2oct() encodes the given curve point p as an octet string into the buffer buf of size len, using the specified conversion form form. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 (\"Elliptic Curve Cryptography\") standard. Similarly the function EC_POINT_oct2point() decodes a curve point into p from the octet string contained in the given buffer buf of size len, conforming to Sec. 2.3.4 of the SECG SEC 1 (\"Elliptic Curve Cryptography\") standard.

The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point p, respectively, to the hexadecimal or BIGNUM representation of the same encoding of the function EC_POINT_point2oct(). Vice versa, similarly to the function EC_POINT_oct2point(), the functions EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or BIGNUM representation into the EC_POINT p.

Notice that, according to the standard, the octet string encoding of the point at infinity for a given curve is fixed to a single octet of value zero and that, vice versa, a single octet of size zero is decoded as the point at infinity.

The function EC_POINT_point2oct() must be supplied with a buffer long enough to store the octet form. The return value provides the number of octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length.

The function EC_POINT_point2buf() allocates a buffer of suitable length and writes an EC_POINT to it in octet format. The allocated buffer is written to *pbuf and its length is returned. The caller must free up the allocated buffer with a call to OPENSSL_free(). Since the allocated buffer value is written to *pbuf the pbuf parameter MUST NOT be NULL.

The function EC_POINT_point2hex() will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free this memory with a subsequent call to OPENSSL_free().

"},{"location":"man3/EC_POINT_new/#return-values","title":"RETURN VALUES","text":"

EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL on error.

The following functions return 1 on success or 0 on error: EC_POINT_copy(), EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point().

EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.

EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required buffer or 0 on error.

EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on error.

EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on error.

EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error.

EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on error.

"},{"location":"man3/EC_POINT_new/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_POINT_new/#history","title":"HISTORY","text":"

EC_POINT_method_of(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_point2bn(), and EC_POINT_bn2point() were deprecated in OpenSSL 3.0.

EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, and EC_POINT_set_compressed_coordinates were added in OpenSSL 1.1.1.

"},{"location":"man3/EC_POINT_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 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.

"},{"location":"man3/ENGINE_add/","title":"ENGINE_add","text":""},{"location":"man3/ENGINE_add/#name","title":"NAME","text":"

ENGINE_get_DH, ENGINE_get_DSA, ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, ENGINE_get_default_DSA, ENGINE_get_default_RAND, ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, ENGINE_get_destroy_function, ENGINE_get_finish_function, ENGINE_get_init_function, ENGINE_get_load_privkey_function, ENGINE_get_load_pubkey_function, ENGINE_load_private_key, ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_RAND, ENGINE_register_RSA, ENGINE_register_all_complete, ENGINE_register_ciphers, ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA, ENGINE_set_default_ciphers, ENGINE_set_default_digests, ENGINE_set_default_string, ENGINE_set_destroy_function, ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, ENGINE_get_table_flags, ENGINE_cleanup, ENGINE_load_builtin_engines, ENGINE_register_all_DH, ENGINE_register_all_DSA, ENGINE_register_all_RAND, ENGINE_register_all_RSA, ENGINE_register_all_ciphers, ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, ENGINE_unregister_DSA, ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, ENGINE_unregister_digests - ENGINE cryptographic module support

"},{"location":"man3/ENGINE_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/engine.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

ENGINE *ENGINE_get_first(void);\nENGINE *ENGINE_get_last(void);\nENGINE *ENGINE_get_next(ENGINE *e);\nENGINE *ENGINE_get_prev(ENGINE *e);\n\nint ENGINE_add(ENGINE *e);\nint ENGINE_remove(ENGINE *e);\n\nENGINE *ENGINE_by_id(const char *id);\n\nint ENGINE_init(ENGINE *e);\nint ENGINE_finish(ENGINE *e);\n\nvoid ENGINE_load_builtin_engines(void);\n\nENGINE *ENGINE_get_default_RSA(void);\nENGINE *ENGINE_get_default_DSA(void);\nENGINE *ENGINE_get_default_DH(void);\nENGINE *ENGINE_get_default_RAND(void);\nENGINE *ENGINE_get_cipher_engine(int nid);\nENGINE *ENGINE_get_digest_engine(int nid);\n\nint ENGINE_set_default_RSA(ENGINE *e);\nint ENGINE_set_default_DSA(ENGINE *e);\nint ENGINE_set_default_DH(ENGINE *e);\nint ENGINE_set_default_RAND(ENGINE *e);\nint ENGINE_set_default_ciphers(ENGINE *e);\nint ENGINE_set_default_digests(ENGINE *e);\nint ENGINE_set_default_string(ENGINE *e, const char *list);\n\nint ENGINE_set_default(ENGINE *e, unsigned int flags);\n\nunsigned int ENGINE_get_table_flags(void);\nvoid ENGINE_set_table_flags(unsigned int flags);\n\nint ENGINE_register_RSA(ENGINE *e);\nvoid ENGINE_unregister_RSA(ENGINE *e);\nvoid ENGINE_register_all_RSA(void);\nint ENGINE_register_DSA(ENGINE *e);\nvoid ENGINE_unregister_DSA(ENGINE *e);\nvoid ENGINE_register_all_DSA(void);\nint ENGINE_register_DH(ENGINE *e);\nvoid ENGINE_unregister_DH(ENGINE *e);\nvoid ENGINE_register_all_DH(void);\nint ENGINE_register_RAND(ENGINE *e);\nvoid ENGINE_unregister_RAND(ENGINE *e);\nvoid ENGINE_register_all_RAND(void);\nint ENGINE_register_ciphers(ENGINE *e);\nvoid ENGINE_unregister_ciphers(ENGINE *e);\nvoid ENGINE_register_all_ciphers(void);\nint ENGINE_register_digests(ENGINE *e);\nvoid ENGINE_unregister_digests(ENGINE *e);\nvoid ENGINE_register_all_digests(void);\nint ENGINE_register_complete(ENGINE *e);\nint ENGINE_register_all_complete(void);\n\nint ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));\nint ENGINE_cmd_is_executable(ENGINE *e, int cmd);\nint ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,\n                    long i, void *p, void (*f)(void), int cmd_optional);\nint ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,\n                           int cmd_optional);\n\nENGINE *ENGINE_new(void);\nint ENGINE_free(ENGINE *e);\nint ENGINE_up_ref(ENGINE *e);\n\nint ENGINE_set_id(ENGINE *e, const char *id);\nint ENGINE_set_name(ENGINE *e, const char *name);\nint ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);\nint ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);\nint ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);\nint ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);\nint ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);\nint ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);\nint ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);\nint ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);\nint ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);\nint ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);\nint ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);\nint ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);\nint ENGINE_set_flags(ENGINE *e, int flags);\nint ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);\n\nconst char *ENGINE_get_id(const ENGINE *e);\nconst char *ENGINE_get_name(const ENGINE *e);\nconst RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);\nconst DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);\nconst DH_METHOD *ENGINE_get_DH(const ENGINE *e);\nconst RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);\nENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);\nENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);\nENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);\nENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);\nENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);\nconst EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);\nconst EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);\nint ENGINE_get_flags(const ENGINE *e);\nconst ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);\n\nEVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,\n                                  UI_METHOD *ui_method, void *callback_data);\nEVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,\n                                 UI_METHOD *ui_method, void *callback_data);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ENGINE_cleanup(void);\n
"},{"location":"man3/ENGINE_add/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

These functions create, manipulate, and use cryptographic modules in the form of ENGINE objects. These objects act as containers for implementations of cryptographic algorithms, and support a reference-counted mechanism to allow them to be dynamically loaded in and out of the running application.

The cryptographic functionality that can be provided by an ENGINE implementation includes the following abstractions;

RSA_METHOD - for providing alternative RSA implementations\nDSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,\n      - similarly for other OpenSSL APIs\nEVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')\nEVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')\nkey-loading - loading public and/or private EVP_PKEY keys\n
"},{"location":"man3/ENGINE_add/#reference-counting-and-handles","title":"Reference counting and handles","text":"

Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be treated as handles - i.e. not only as pointers, but also as references to the underlying ENGINE object. Ie. one should obtain a new reference when making copies of an ENGINE pointer if the copies will be used (and released) independently.

ENGINE objects have two levels of reference-counting to match the way in which the objects are used. At the most basic level, each ENGINE pointer is inherently a structural reference - a structural reference is required to use the pointer value at all, as this kind of reference is a guarantee that the structure can not be deallocated until the reference is released.

However, a structural reference provides no guarantee that the ENGINE is initialised and able to use any of its cryptographic implementations. Indeed it's quite possible that most ENGINEs will not initialise at all in typical environments, as ENGINEs are typically used to support specialised hardware. To use an ENGINE's functionality, you need a functional reference. This kind of reference can be considered a specialised form of structural reference, because each functional reference implicitly contains a structural reference as well - however to avoid difficult-to-find programming bugs, it is recommended to treat the two kinds of reference independently. If you have a functional reference to an ENGINE, you have a guarantee that the ENGINE has been initialised and is ready to perform cryptographic operations, and will remain initialised until after you have released your reference.

Structural references

This basic type of reference is used for instantiating new ENGINEs, iterating across OpenSSL's internal linked-list of loaded ENGINEs, reading information about an ENGINE, etc. Essentially a structural reference is sufficient if you only need to query or manipulate the data of an ENGINE implementation rather than use its functionality.

The ENGINE_new() function returns a structural reference to a new (empty) ENGINE object. There are other ENGINE API functions that return structural references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(), ENGINE_get_prev(). All structural references should be released by a corresponding to call to the ENGINE_free() function - the ENGINE object itself will only actually be cleaned up and deallocated when the last structural reference is released. If the argument to ENGINE_free() is NULL, nothing is done.

It should also be noted that many ENGINE API function calls that accept a structural reference will internally obtain another reference - typically this happens whenever the supplied ENGINE will be needed by OpenSSL after the function has returned. Eg. the function to add a new ENGINE to OpenSSL's internal list is ENGINE_add() - if this function returns success, then OpenSSL will have stored a new structural reference internally so the caller is still responsible for freeing their own reference with ENGINE_free() when they are finished with it. In a similar way, some functions will automatically release the structural reference passed to it if part of the function's job is to do so. Eg. the ENGINE_get_next() and ENGINE_get_prev() functions are used for iterating across the internal ENGINE list - they will return a new structural reference to the next (or previous) ENGINE in the list or NULL if at the end (or beginning) of the list, but in either case the structural reference passed to the function is released on behalf of the caller.

To clarify a particular function's handling of references, one should always consult that function's documentation \"man\" page, or failing that the <openssl/engine.h> header file includes some hints.

Functional references

As mentioned, functional references exist when the cryptographic functionality of an ENGINE is required to be available. A functional reference can be obtained in one of two ways; from an existing structural reference to the required ENGINE, or by asking OpenSSL for the default operational ENGINE for a given cryptographic purpose.

To obtain a functional reference from an existing structural reference, call the ENGINE_init() function. This returns zero if the ENGINE was not already operational and couldn't be successfully initialised (e.g. lack of system drivers, no special hardware attached, etc), otherwise it will return nonzero to indicate that the ENGINE is now operational and will have allocated a new functional reference to the ENGINE. All functional references are released by calling ENGINE_finish() (which removes the implicit structural reference as well).

The second way to get a functional reference is by asking OpenSSL for a default implementation for a given task, e.g. by ENGINE_get_default_RSA(), ENGINE_get_default_cipher_engine(), etc. These are discussed in the next section, though they are not usually required by application programmers as they are used automatically when creating and using the relevant algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.

"},{"location":"man3/ENGINE_add/#default-implementations","title":"Default implementations","text":"

For each supported abstraction, the ENGINE code maintains an internal table of state to control which implementations are available for a given abstraction and which should be used by default. These implementations are registered in the tables and indexed by an 'nid' value, because abstractions like EVP_CIPHER and EVP_DIGEST support many distinct algorithms and modes, and ENGINEs can support arbitrarily many of them. In the case of other abstractions like RSA, DSA, etc, there is only one \"algorithm\" so all implementations implicitly register using the same 'nid' index.

When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g. when calling RSA_new_method(NULL)), a \"get_default\" call will be made to the ENGINE subsystem to process the corresponding state table and return a functional reference to an initialised ENGINE whose implementation should be used. If no ENGINE should (or can) be used, it will return NULL and the caller will operate with a NULL ENGINE handle - this usually equates to using the conventional software implementation. In the latter case, OpenSSL will from then on behave the way it used to before the ENGINE API existed.

Each state table has a flag to note whether it has processed this \"get_default\" query since the table was last modified, because to process this question it must iterate across all the registered ENGINEs in the table trying to initialise each of them in turn, in case one of them is operational. If it returns a functional reference to an ENGINE, it will also cache another reference to speed up processing future queries (without needing to iterate across the table). Likewise, it will cache a NULL response if no ENGINE was available so that future queries won't repeat the same iteration unless the state table changes. This behaviour can also be changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using ENGINE_set_table_flags()), no attempted initialisations will take place, instead the only way for the state table to return a non-NULL ENGINE to the \"get_default\" query will be if one is expressly set in the table. Eg. ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except that it also sets the state table's cached response for the \"get_default\" query. In the case of abstractions like EVP_CIPHER, where implementations are indexed by 'nid', these flags and cached-responses are distinct for each 'nid' value.

"},{"location":"man3/ENGINE_add/#application-requirements","title":"Application requirements","text":"

This section will explain the basic things an application programmer should support to make the most useful elements of the ENGINE functionality available to the user. The first thing to consider is whether the programmer wishes to make alternative ENGINE modules available to the application and user. OpenSSL maintains an internal linked list of \"visible\" ENGINEs from which it has to operate - at start-up, this list is empty and in fact if an application does not call any ENGINE API calls and it uses static linking against openssl, then the resulting application binary will not contain any alternative ENGINE code at all. So the first consideration is whether any/all available ENGINE implementations should be made visible to OpenSSL - this is controlled by calling the various \"load\" functions.

The fact that ENGINEs are made visible to OpenSSL (and thus are linked into the program and loaded into memory at run-time) does not mean they are \"registered\" or called into use by OpenSSL automatically - that behaviour is something for the application to control. Some applications will want to allow the user to specify exactly which ENGINE they want used if any is to be used at all. Others may prefer to load all support and have OpenSSL automatically use at run-time any ENGINE that is able to successfully initialise - i.e. to assume that this corresponds to acceleration hardware attached to the machine or some such thing. There are probably numerous other ways in which applications may prefer to handle things, so we will simply illustrate the consequences as they apply to a couple of simple cases and leave developers to consider these and the source code to openssl's built-in utilities as guides.

If no ENGINE API functions are called within an application, then OpenSSL will not allocate any internal resources. Prior to OpenSSL 1.1.0, however, if any ENGINEs are loaded, even if not registered or used, it was necessary to call ENGINE_cleanup() before the program exits.

Using a specific ENGINE implementation

Here we'll assume an application has been configured by its user or admin to want to use the \"ACME\" ENGINE if it is available in the version of OpenSSL the application was compiled with. If it is available, it should be used by default for all RSA, DSA, and symmetric cipher operations, otherwise OpenSSL should use its built-in software as per usual. The following code illustrates how to approach this;

ENGINE *e;\nconst char *engine_id = \"ACME\";\nENGINE_load_builtin_engines();\ne = ENGINE_by_id(engine_id);\nif (!e)\n    /* the engine isn't available */\n    return;\nif (!ENGINE_init(e)) {\n    /* the engine couldn't initialise, release 'e' */\n    ENGINE_free(e);\n    return;\n}\nif (!ENGINE_set_default_RSA(e))\n    /*\n     * This should only happen when 'e' can't initialise, but the previous\n     * statement suggests it did.\n     */\n    abort();\nENGINE_set_default_DSA(e);\nENGINE_set_default_ciphers(e);\n/* Release the functional reference from ENGINE_init() */\nENGINE_finish(e);\n/* Release the structural reference from ENGINE_by_id() */\nENGINE_free(e);\n

Automatically using built-in ENGINE implementations

Here we'll assume we want to load and register all ENGINE implementations bundled with OpenSSL, such that for any cryptographic algorithm required by OpenSSL - if there is an ENGINE that implements it and can be initialised, it should be used. The following code illustrates how this can work;

/* Load all bundled ENGINEs into memory and make them visible */\nENGINE_load_builtin_engines();\n/* Register all of them for every algorithm they collectively implement */\nENGINE_register_all_complete();\n

That's all that's required. Eg. the next time OpenSSL tries to set up an RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to ENGINE_init() and if any of those succeed, that ENGINE will be set as the default for RSA use from then on.

"},{"location":"man3/ENGINE_add/#advanced-configuration-support","title":"Advanced configuration support","text":"

There is a mechanism supported by the ENGINE framework that allows each ENGINE implementation to define an arbitrary set of configuration \"commands\" and expose them to OpenSSL and any applications based on OpenSSL. This mechanism is entirely based on the use of name-value pairs and assumes ASCII input (no unicode or UTF for now!), so it is ideal if applications want to provide a transparent way for users to provide arbitrary configuration \"directives\" directly to such ENGINEs. It is also possible for the application to dynamically interrogate the loaded ENGINE implementations for the names, descriptions, and input flags of their available \"control commands\", providing a more flexible configuration scheme. However, if the user is expected to know which ENGINE device he/she is using (in the case of specialised hardware, this goes without saying) then applications may not need to concern themselves with discovering the supported control commands and simply prefer to pass settings into ENGINEs exactly as they are provided by the user.

Before illustrating how control commands work, it is worth mentioning what they are typically used for. Broadly speaking there are two uses for control commands; the first is to provide the necessary details to the implementation (which may know nothing at all specific to the host system) so that it can be initialised for use. This could include the path to any driver or config files it needs to load, required network addresses, smart-card identifiers, passwords to initialise protected devices, logging information, etc etc. This class of commands typically needs to be passed to an ENGINE before attempting to initialise it, i.e. before calling ENGINE_init(). The other class of commands consist of settings or operations that tweak certain behaviour or cause certain operations to take place, and these commands may work either before or after ENGINE_init(), or in some cases both. ENGINE implementations should provide indications of this in the descriptions attached to built-in control commands and/or in external product documentation.

Issuing control commands to an ENGINE

Let's illustrate by example; a function for which the caller supplies the name of the ENGINE it wishes to use, a table of string-pairs for use before initialisation, and another table for use after initialisation. Note that the string-pairs used for control commands consist of a command \"name\" followed by the command \"parameter\" - the parameter could be NULL in some cases but the name can not. This function should initialise the ENGINE (issuing the \"pre\" commands beforehand and the \"post\" commands afterwards) and set it as the default for everything except RAND and then return a boolean success or failure.

int generic_load_engine_fn(const char *engine_id,\n                           const char **pre_cmds, int pre_num,\n                           const char **post_cmds, int post_num)\n{\n    ENGINE *e = ENGINE_by_id(engine_id);\n    if (!e) return 0;\n    while (pre_num--) {\n        if (!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {\n            fprintf(stderr, \"Failed command (%s - %s:%s)\\n\", engine_id,\n                    pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : \"(NULL)\");\n            ENGINE_free(e);\n            return 0;\n        }\n        pre_cmds += 2;\n    }\n    if (!ENGINE_init(e)) {\n        fprintf(stderr, \"Failed initialisation\\n\");\n        ENGINE_free(e);\n        return 0;\n    }\n    /*\n     * ENGINE_init() returned a functional reference, so free the structural\n     * reference from ENGINE_by_id().\n     */\n    ENGINE_free(e);\n    while (post_num--) {\n        if (!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {\n            fprintf(stderr, \"Failed command (%s - %s:%s)\\n\", engine_id,\n                    post_cmds[0], post_cmds[1] ? post_cmds[1] : \"(NULL)\");\n            ENGINE_finish(e);\n            return 0;\n        }\n        post_cmds += 2;\n    }\n    ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);\n    /* Success */\n    return 1;\n}\n

Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can relax the semantics of the function - if set nonzero it will only return failure if the ENGINE supported the given command name but failed while executing it, if the ENGINE doesn't support the command name it will simply return success without doing anything. In this case we assume the user is only supplying commands specific to the given ENGINE so we set this to FALSE.

Discovering supported control commands

It is possible to discover at run-time the names, numerical-ids, descriptions and input parameters of the control commands supported by an ENGINE using a structural reference. Note that some control commands are defined by OpenSSL itself and it will intercept and handle these control commands on behalf of the ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command. <openssl/engine.h> defines an index, ENGINE_CMD_BASE, that all control commands implemented by ENGINEs should be numbered from. Any command value lower than this symbol is considered a \"generic\" command is handled directly by the OpenSSL core routines.

It is using these \"core\" control commands that one can discover the control commands implemented by a given ENGINE, specifically the commands:

ENGINE_HAS_CTRL_FUNCTION\nENGINE_CTRL_GET_FIRST_CMD_TYPE\nENGINE_CTRL_GET_NEXT_CMD_TYPE\nENGINE_CTRL_GET_CMD_FROM_NAME\nENGINE_CTRL_GET_NAME_LEN_FROM_CMD\nENGINE_CTRL_GET_NAME_FROM_CMD\nENGINE_CTRL_GET_DESC_LEN_FROM_CMD\nENGINE_CTRL_GET_DESC_FROM_CMD\nENGINE_CTRL_GET_CMD_FLAGS\n

Whilst these commands are automatically processed by the OpenSSL framework code, they use various properties exposed by each ENGINE to process these queries. An ENGINE has 3 properties it exposes that can affect how this behaves; it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in the ENGINE's flags, and it can expose an array of control command descriptions. If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will simply pass all these \"core\" control commands directly to the ENGINE's ctrl() handler (and thus, it must have supplied one), so it is up to the ENGINE to reply to these \"discovery\" commands itself. If that flag is not set, then the OpenSSL framework code will work with the following rules:

if no ctrl() handler supplied;\n    ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),\n    all other commands fail.\nif a ctrl() handler was supplied but no array of control commands;\n    ENGINE_HAS_CTRL_FUNCTION returns TRUE,\n    all other commands fail.\nif a ctrl() handler and array of control commands was supplied;\n    ENGINE_HAS_CTRL_FUNCTION returns TRUE,\n    all other commands proceed processing ...\n

If the ENGINE's array of control commands is empty then all other commands will fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the identifier of a command supported by the ENGINE and returns the next command identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string name for a command and returns the corresponding identifier or fails if no such command name exists, and the remaining commands take a command identifier and return properties of the corresponding commands. All except ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, or populate a supplied character buffer with a copy of the command name or description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following possible values:

ENGINE_CMD_FLAG_NUMERIC\nENGINE_CMD_FLAG_STRING\nENGINE_CMD_FLAG_NO_INPUT\nENGINE_CMD_FLAG_INTERNAL\n

If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely informational to the caller - this flag will prevent the command being usable for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). \"INTERNAL\" commands are not intended to be exposed to text-based configuration by applications, administrations, users, etc. These can support arbitrary operations via ENGINE_ctrl(), including passing to and/or from the control commands data of any arbitrary type. These commands are supported in the discovery mechanisms simply to allow applications to determine if an ENGINE supports certain specific commands it might want to use (e.g. application \"foo\" might query various ENGINEs to see if they implement \"FOO_GET_VENDOR_LOGO_GIF\" - and ENGINE could therefore decide whether or not to support this \"foo\"-specific extension).

"},{"location":"man3/ENGINE_add/#environment","title":"ENVIRONMENT","text":""},{"location":"man3/ENGINE_add/#return-values","title":"RETURN VALUES","text":"

ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev() return a valid ENGINE structure or NULL if an error occurred.

ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error.

ENGINE_by_id() returns a valid ENGINE structure or NULL if an error occurred.

ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error.

All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and ENGINE_get_digest_engine() return a valid ENGINE structure on success or NULL if an error occurred.

All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error.

ENGINE_set_default() returns 1 on success or 0 on error.

ENGINE_get_table_flags() returns an unsigned integer value representing the global table flags which are used to control the registration behaviour of ENGINE implementations.

All ENGINE_register_TYPE() functions return 1 on success or 0 on error.

ENGINE_register_complete() and ENGINE_register_all_complete() always return 1.

ENGINE_ctrl() returns a positive value on success or others on error.

ENGINE_cmd_is_executable() returns 1 if cmd is executable or 0 otherwise.

ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error.

ENGINE_new() returns a valid ENGINE structure on success or NULL if an error occurred.

ENGINE_free() always returns 1.

ENGINE_up_ref() returns 1 on success or 0 on error.

ENGINE_set_id() and ENGINE_set_name() return 1 on success or 0 on error.

All other ENGINE_set_* functions return 1 on success or 0 on error.

ENGINE_get_id() and ENGINE_get_name() return a string representing the identifier and the name of the ENGINE e respectively.

ENGINE_get_RSA(), ENGINE_get_DSA(), ENGINE_get_DH() and ENGINE_get_RAND() return corresponding method structures for each algorithms.

ENGINE_get_destroy_function(), ENGINE_get_init_function(), ENGINE_get_finish_function(), ENGINE_get_ctrl_function(), ENGINE_get_load_privkey_function(), ENGINE_get_load_pubkey_function(), ENGINE_get_ciphers() and ENGINE_get_digests() return corresponding function pointers of the callbacks.

ENGINE_get_cipher() returns a valid EVP_CIPHER structure on success or NULL if an error occurred.

ENGINE_get_digest() returns a valid EVP_MD structure on success or NULL if an error occurred.

ENGINE_get_flags() returns an integer representing the ENGINE flags which are used to control various behaviours of an ENGINE.

ENGINE_get_cmd_defns() returns an ENGINE_CMD_DEFN structure or NULL if it's not set.

ENGINE_load_private_key() and ENGINE_load_public_key() return a valid EVP_PKEY structure on success or NULL if an error occurred.

"},{"location":"man3/ENGINE_add/#see-also","title":"SEE ALSO","text":"

OPENSSL_init_crypto(3), RSA_new_method(3), DSA_new(3), DH_new(3), RAND_bytes(3), config(5)

"},{"location":"man3/ENGINE_add/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup done by OPENSSL_cleanup() and should not be used.

"},{"location":"man3/ENGINE_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2024 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.

"},{"location":"man3/ERR_GET_LIB/","title":"ERR_GET_LIB","text":""},{"location":"man3/ERR_GET_LIB/#name","title":"NAME","text":"

ERR_GET_LIB, ERR_GET_REASON, ERR_FATAL_ERROR - get information from error codes

"},{"location":"man3/ERR_GET_LIB/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_GET_LIB(unsigned long e);\n\nint ERR_GET_REASON(unsigned long e);\n\nint ERR_FATAL_ERROR(unsigned long e);\n
"},{"location":"man3/ERR_GET_LIB/#description","title":"DESCRIPTION","text":"

The error code returned by ERR_get_error() consists of a library number and reason code. ERR_GET_LIB() and ERR_GET_REASON() can be used to extract these.

ERR_FATAL_ERROR() indicates whether a given error code is a fatal error.

The library number describes where the error occurred, the reason code is the information about what went wrong.

Each sub-library of OpenSSL has a unique library number; the reason code is unique within each sub-library. Note that different libraries may use the same value to signal different reasons.

ERR_R_... reason codes such as ERR_R_MALLOC_FAILURE are globally unique. However, when checking for sub-library specific reason codes, be sure to also compare the library number.

ERR_GET_LIB(), ERR_GET_REASON(), and ERR_FATAL_ERROR() are macros.

"},{"location":"man3/ERR_GET_LIB/#return-values","title":"RETURN VALUES","text":"

The library number, reason code, and whether the error is fatal, respectively. Starting with OpenSSL 3.0.0, the function code is always set to zero.

"},{"location":"man3/ERR_GET_LIB/#notes","title":"NOTES","text":"

Applications should not make control flow decisions based on specific error codes. Error codes are subject to change at any time (even in patch releases of OpenSSL). A particular error code can only be considered meaningful for control flow decisions if it is explicitly documented as such. New failure codes may still appear at any time.

"},{"location":"man3/ERR_GET_LIB/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ERR_GET_LIB/#history","title":"HISTORY","text":"

ERR_GET_LIB() and ERR_GET_REASON() are available in all versions of OpenSSL.

ERR_GET_FUNC() was removed in OpenSSL 3.0.

"},{"location":"man3/ERR_GET_LIB/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/ERR_clear_error/","title":"ERR_clear_error","text":""},{"location":"man3/ERR_clear_error/#name","title":"NAME","text":"

ERR_clear_error - clear the error queue

"},{"location":"man3/ERR_clear_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_clear_error(void);\n
"},{"location":"man3/ERR_clear_error/#description","title":"DESCRIPTION","text":"

ERR_clear_error() empties the current thread's error queue.

"},{"location":"man3/ERR_clear_error/#return-values","title":"RETURN VALUES","text":"

ERR_clear_error() has no return value.

"},{"location":"man3/ERR_clear_error/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ERR_clear_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/ERR_error_string/","title":"ERR_error_string","text":""},{"location":"man3/ERR_error_string/#name","title":"NAME","text":"

ERR_error_string, ERR_error_string_n, ERR_lib_error_string, ERR_func_error_string, ERR_reason_error_string - obtain human-readable error message

"},{"location":"man3/ERR_error_string/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nchar *ERR_error_string(unsigned long e, char *buf);\nvoid ERR_error_string_n(unsigned long e, char *buf, size_t len);\n\nconst char *ERR_lib_error_string(unsigned long e);\nconst char *ERR_reason_error_string(unsigned long e);\n

Deprecated in OpenSSL 3.0:

const char *ERR_func_error_string(unsigned long e);\n
"},{"location":"man3/ERR_error_string/#description","title":"DESCRIPTION","text":"

ERR_error_string() generates a human-readable string representing the error code e, and places it at buf. buf must be at least 256 bytes long. If buf is NULL, the error string is placed in a static buffer. Note that this function is not thread-safe and does no checks on the size of the buffer; use ERR_error_string_n() instead.

ERR_error_string_n() is a variant of ERR_error_string() that writes at most len characters (including the terminating 0) and truncates the string if necessary. For ERR_error_string_n(), buf MUST NOT be NULL.

The string will have the following format:

error:[error code]:[library name]::[reason string]\n

error code is an 8 digit hexadecimal number, library name and reason string are ASCII text.

ERR_lib_error_string() and ERR_reason_error_string() return the library name and reason string respectively.

If there is no text string registered for the given error code, the error string will contain the numeric code.

ERR_print_errors(3) can be used to print all error codes currently in the queue.

"},{"location":"man3/ERR_error_string/#return-values","title":"RETURN VALUES","text":"

ERR_error_string() returns a pointer to a static buffer containing the string if buf == NULL, buf otherwise.

ERR_lib_error_string() and ERR_reason_error_string() return the strings, and NULL if none is registered for the error code.

ERR_func_error_string() returns NULL.

"},{"location":"man3/ERR_error_string/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), ERR_print_errors(3)

"},{"location":"man3/ERR_error_string/#history","title":"HISTORY","text":"

ERR_func_error_string() became deprecated in OpenSSL 3.0.

"},{"location":"man3/ERR_error_string/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/ERR_get_error/","title":"ERR_get_error","text":""},{"location":"man3/ERR_get_error/#name","title":"NAME","text":"

ERR_get_error, ERR_peek_error, ERR_peek_last_error, ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, ERR_peek_error_func, ERR_peek_last_error_func, ERR_peek_error_data, ERR_peek_last_error_data, ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all, ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data - obtain error code and data

"},{"location":"man3/ERR_get_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nunsigned long ERR_get_error(void);\nunsigned long ERR_peek_error(void);\nunsigned long ERR_peek_last_error(void);\n\nunsigned long ERR_peek_error_line(const char **file, int *line);\nunsigned long ERR_peek_last_error_line(const char **file, int *line);\n\nunsigned long ERR_peek_error_func(const char **func);\nunsigned long ERR_peek_last_error_func(const char **func);\n\nunsigned long ERR_peek_error_data(const char **data, int *flags);\nunsigned long ERR_peek_last_error_data(const char **data, int *flags);\n\nunsigned long ERR_get_error_all(const char **file, int *line,\n                                const char **func,\n                                const char **data, int *flags);\nunsigned long ERR_peek_error_all(const char **file, int *line,\n                                 const char **func,\n                                 const char **data, int *flags);\nunsigned long ERR_peek_last_error_all(const char **file, int *line,\n                                      const char *func,\n                                      const char **data, int *flags);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

unsigned long ERR_get_error_line(const char **file, int *line);\nunsigned long ERR_get_error_line_data(const char **file, int *line,\n                                      const char **data, int *flags);\nunsigned long ERR_peek_error_line_data(const char **file, int *line,\n                                       const char **data, int *flags);\nunsigned long ERR_peek_last_error_line_data(const char **file, int *line,\n                                            const char **data, int *flags);\n
"},{"location":"man3/ERR_get_error/#description","title":"DESCRIPTION","text":"

ERR_get_error() returns the earliest error code from the thread's error queue and removes the entry. This function can be called repeatedly until there are no more error codes to return.

ERR_peek_error() returns the earliest error code from the thread's error queue without modifying it.

ERR_peek_last_error() returns the latest error code from the thread's error queue without modifying it.

See ERR_GET_LIB(3) for obtaining further specific information such as the reason of the error, and ERR_error_string(3) for human-readable error messages.

ERR_get_error_all() is the same as ERR_get_error(), but on success it additionally stores the filename, line number and function where the error occurred in *file, *line and *func, and also extra text and flags in *data, *flags. If any of those parameters are NULL, it will not be changed. An unset filename is indicated as \"\", i.e. an empty string. An unset line number is indicated as 0. An unset function name is indicated as \"\", i.e. an empty string.

A pointer returned this way by these functions and the ones below is valid until the respective entry is overwritten in the error queue.

ERR_peek_error_line() and ERR_peek_last_error_line() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store the filename and line number where the error occurred in *file and *line, as far as they are not NULL. An unset filename is indicated as \"\", i.e., an empty string. An unset line number is indicated as 0.

ERR_peek_error_func() and ERR_peek_last_error_func() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store the name of the function where the error occurred in *func, unless it is NULL. An unset function name is indicated as \"\".

ERR_peek_error_data() and ERR_peek_last_error_data() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store additional data and flags associated with the error code in *data and *flags, as far as they are not NULL. Unset data is indicated as \"\". In this case the value given for the flag is irrelevant (and equals 0). *data contains a string if *flags&ERR_TXT_STRING is true.

ERR_peek_error_all() and ERR_peek_last_error_all() are combinations of all of the above.

ERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data() and ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all(), and may give confusing results. They should no longer be used and are therefore deprecated.

An application MUST NOT free the *data pointer (or any other pointers returned by these functions) with OPENSSL_free() as freeing is handled automatically by the error library.

"},{"location":"man3/ERR_get_error/#return-values","title":"RETURN VALUES","text":"

The error code, or 0 if there is no error in the queue.

"},{"location":"man3/ERR_get_error/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3), ERR_GET_LIB(3)

"},{"location":"man3/ERR_get_error/#history","title":"HISTORY","text":"

ERR_peek_error_func(), ERR_peek_last_error_func(), ERR_peek_error_data(), ERR_peek_last_error_data(), ERR_peek_error_all() and ERR_peek_last_error_all() were added in OpenSSL 3.0.

ERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data() and ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.

"},{"location":"man3/ERR_get_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/ERR_load_crypto_strings/","title":"ERR_load_crypto_strings","text":""},{"location":"man3/ERR_load_crypto_strings/#name","title":"NAME","text":"

ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - load and free error strings

"},{"location":"man3/ERR_load_crypto_strings/#synopsis","title":"SYNOPSIS","text":"

The following functions have been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/err.h>\n\nvoid ERR_load_crypto_strings(void);\nvoid ERR_free_strings(void);\n\n#include <openssl/ssl.h>\n\nvoid SSL_load_error_strings(void);\n
"},{"location":"man3/ERR_load_crypto_strings/#description","title":"DESCRIPTION","text":"

ERR_load_crypto_strings() registers the error strings for all libcrypto functions. SSL_load_error_strings() does the same, but also registers the libssl error strings.

In versions prior to OpenSSL 1.1.0, ERR_free_strings() releases any resources created by the above functions.

"},{"location":"man3/ERR_load_crypto_strings/#return-values","title":"RETURN VALUES","text":"

ERR_load_crypto_strings(), SSL_load_error_strings() and ERR_free_strings() return no values.

"},{"location":"man3/ERR_load_crypto_strings/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3)

"},{"location":"man3/ERR_load_crypto_strings/#history","title":"HISTORY","text":"

The ERR_load_crypto_strings(), SSL_load_error_strings(), and ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto() and OPENSSL_init_ssl() and should not be used.

"},{"location":"man3/ERR_load_crypto_strings/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 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.

"},{"location":"man3/ERR_load_strings/","title":"ERR_load_strings","text":""},{"location":"man3/ERR_load_strings/#name","title":"NAME","text":"

ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load arbitrary error strings

"},{"location":"man3/ERR_load_strings/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_load_strings(int lib, ERR_STRING_DATA *str);\n\nint ERR_get_next_error_library(void);\n\nunsigned long ERR_PACK(int lib, int func, int reason);\n
"},{"location":"man3/ERR_load_strings/#description","title":"DESCRIPTION","text":"

ERR_load_strings() registers error strings for library number lib.

str is an array of error string data:

typedef struct ERR_string_data_st\n{\n    unsigned long error;\n    char *string;\n} ERR_STRING_DATA;\n

The error code is generated from the library number and a function and reason code: error = ERR_PACK(lib, func, reason). ERR_PACK() is a macro.

The last entry in the array is {0,0}.

ERR_get_next_error_library() can be used to assign library numbers to user libraries at run time.

"},{"location":"man3/ERR_load_strings/#return-values","title":"RETURN VALUES","text":"

ERR_load_strings() returns 1 for success and 0 for failure. ERR_PACK() returns the error code. ERR_get_next_error_library() returns zero on failure, otherwise a new library number.

"},{"location":"man3/ERR_load_strings/#see-also","title":"SEE ALSO","text":"

ERR_load_strings(3)

"},{"location":"man3/ERR_load_strings/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 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.

"},{"location":"man3/ERR_new/","title":"ERR_new","text":""},{"location":"man3/ERR_new/#name","title":"NAME","text":"

ERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error - Error recording building blocks

"},{"location":"man3/ERR_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_new(void);\nvoid ERR_set_debug(const char *file, int line, const char *func);\nvoid ERR_set_error(int lib, int reason, const char *fmt, ...);\nvoid ERR_vset_error(int lib, int reason, const char *fmt, va_list args);\n
"},{"location":"man3/ERR_new/#description","title":"DESCRIPTION","text":"

The functions described here are generally not used directly, but rather through macros such as ERR_raise(3). They can still be useful for anyone that wants to make their own macros.

ERR_new() allocates a new slot in the thread's error queue.

ERR_set_debug() sets the debug information related to the current error in the thread's error queue. The values that can be given are the filename file, line in the file line and the name of the function func where the error occurred. The names must be constant, this function will only save away the pointers, not copy the strings.

ERR_set_error() sets the error information, which are the library number lib and the reason code reason, and additional data as a format string fmt and an arbitrary number of arguments. The additional data is processed with BIO_snprintf(3) to form the additional data string, which is allocated and store in the error record.

ERR_vset_error() works like ERR_set_error(), but takes a va_list argument instead of a variable number of arguments.

"},{"location":"man3/ERR_new/#return-values","title":"RETURN VALUES","text":"

ERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error do not return any values.

"},{"location":"man3/ERR_new/#notes","title":"NOTES","text":"

The library number is unique to each unit that records errors. OpenSSL has a number of preallocated ones for its own uses, but others may allocate their own library number dynamically with ERR_get_next_error_library(3).

Reason codes are unique within each library, and may have an associated set of strings as a short description of the reason. For dynamically allocated library numbers, reason strings are recorded with ERR_load_strings(3).

Provider authors are supplied with core versions of these functions, see provider-base(7).

"},{"location":"man3/ERR_new/#see-also","title":"SEE ALSO","text":"

ERR_raise(3), ERR_get_next_error_library(3), ERR_load_strings(3), BIO_snprintf(3), provider-base(7)

"},{"location":"man3/ERR_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ERR_print_errors/","title":"ERR_print_errors","text":""},{"location":"man3/ERR_print_errors/#name","title":"NAME","text":"

ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb - print error messages

"},{"location":"man3/ERR_print_errors/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_print_errors(BIO *bp);\nvoid ERR_print_errors_fp(FILE *fp);\nvoid ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u),\n                         void *u);\n
"},{"location":"man3/ERR_print_errors/#description","title":"DESCRIPTION","text":"

ERR_print_errors() is a convenience function that prints the error strings for all errors that OpenSSL has recorded to bp, thus emptying the error queue.

ERR_print_errors_fp() is the same, except that the output goes to a FILE.

ERR_print_errors_cb() is the same, except that the callback function, cb, is called for each error line with the string, length, and userdata u as the callback parameters.

The error strings will have the following format:

[pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message]\n

error code is an 8 digit hexadecimal number. library name, function name and reason string are ASCII text, as is optional text message if one was set for the respective error code.

If there is no text string registered for the given error code, the error string will contain the numeric code.

"},{"location":"man3/ERR_print_errors/#return-values","title":"RETURN VALUES","text":"

ERR_print_errors() and ERR_print_errors_fp() return no values.

"},{"location":"man3/ERR_print_errors/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3), ERR_get_error(3)

"},{"location":"man3/ERR_print_errors/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ERR_put_error/","title":"ERR_put_error","text":""},{"location":"man3/ERR_put_error/#name","title":"NAME","text":"

ERR_raise, ERR_raise_data, ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, ERR_add_error_txt, ERR_add_error_mem_bio - record an error

"},{"location":"man3/ERR_put_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_raise(int lib, int reason);\nvoid ERR_raise_data(int lib, int reason, const char *fmt, ...);\n\nvoid ERR_add_error_data(int num, ...);\nvoid ERR_add_error_vdata(int num, va_list arg);\nvoid ERR_add_error_txt(const char *sep, const char *txt);\nvoid ERR_add_error_mem_bio(const char *sep, BIO *bio);\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_put_error(int lib, int func, int reason, const char *file, int line);\n
"},{"location":"man3/ERR_put_error/#description","title":"DESCRIPTION","text":"

ERR_raise() adds a new error to the thread's error queue. The error occurred in the library lib for the reason given by the reason code. Furthermore, the name of the file, the line, and name of the function where the error occurred is saved with the error record.

ERR_raise_data() does the same thing as ERR_raise(), but also lets the caller specify additional information as a format string fmt and an arbitrary number of values, which are processed with BIO_snprintf(3).

ERR_put_error() adds an error code to the thread's error queue. It signals that the error of reason code reason occurred in function func of library lib, in line number line of file. This function is usually called by a macro.

ERR_add_error_data() associates the concatenation of its num string arguments as additional data with the error code added last. ERR_add_error_vdata() is similar except the argument is a va_list. Multiple calls to these functions append to the current top of the error queue. The total length of the string data per error is limited to 4096 characters.

ERR_add_error_txt() appends the given text string as additional data to the last error queue entry, after inserting the optional separator string if it is not NULL and the top error entry does not yet have additional data. In case the separator is at the end of the text it is not appended to the data. The sep argument may be for instance \"\\n\" to insert a line break when needed. If the associated data would become more than 4096 characters long (which is the limit given above) it is split over sufficiently many new copies of the last error queue entry.

ERR_add_error_mem_bio() is the same as ERR_add_error_txt() except that the text string is taken from the given memory BIO. It appends '\\0' to the BIO contents if not already NUL-terminated.

ERR_load_strings(3) can be used to register error strings so that the application can a generate human-readable error messages for the error code.

"},{"location":"man3/ERR_put_error/#reporting-errors","title":"Reporting errors","text":""},{"location":"man3/ERR_put_error/#openssl-library-reports","title":"OpenSSL library reports","text":"

Each OpenSSL sub-library has library code ERR_LIB_XXX and has its own set of reason codes XXX_R_.... These are both passed in combination to ERR_raise() and ERR_raise_data(), and the combination ultimately produces the correct error text for the reported error.

All these macros and the numbers they have as values are specific to OpenSSL's libraries. OpenSSL reason codes normally consist of textual error descriptions. For example, the function ssl3_read_bytes() reports a \"handshake failure\" as follows:

ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE);\n

There are two exceptions:

"},{"location":"man3/ERR_put_error/#other-pieces-of-software","title":"Other pieces of software","text":"

Other pieces of software that may want to use OpenSSL's error reporting system, such as engines or applications, must normally get their own numbers.

The exceptions mentioned in \"OpenSSL library reports\" above are valid for other pieces of software, i.e. they may use ERR_LIB_SYS to report system errors:

ERR_raise(ERR_LIB_SYS, errno);\n

... and they may use ERR_R_XXX macros together with their own \"library\" code.

int app_lib_code = ERR_get_next_error_library();\n\n/* ... */\n\nERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT);\n
"},{"location":"man3/ERR_put_error/#return-values","title":"RETURN VALUES","text":"

ERR_raise(), ERR_raise_data(), ERR_put_error(), ERR_add_error_data(), ERR_add_error_vdata() ERR_add_error_txt(), and ERR_add_error_mem_bio() return no values.

"},{"location":"man3/ERR_put_error/#notes","title":"NOTES","text":"

ERR_raise(), ERR_raise() and ERR_put_error() are implemented as macros.

"},{"location":"man3/ERR_put_error/#see-also","title":"SEE ALSO","text":"

ERR_load_strings(3), ERR_get_next_error_library(3)

"},{"location":"man3/ERR_put_error/#history","title":"HISTORY","text":"

ERR_raise, ERR_raise_data, ERR_add_error_txt() and ERR_add_error_mem_bio() were added in OpenSSL 3.0.

"},{"location":"man3/ERR_put_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/ERR_remove_state/","title":"ERR_remove_state","text":""},{"location":"man3/ERR_remove_state/#name","title":"NAME","text":"

ERR_remove_thread_state, ERR_remove_state - DEPRECATED

"},{"location":"man3/ERR_remove_state/#synopsis","title":"SYNOPSIS","text":"

The following function has been deprecated since OpenSSL 1.0.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_remove_state(unsigned long tid);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_remove_thread_state(void *tid);\n
"},{"location":"man3/ERR_remove_state/#description","title":"DESCRIPTION","text":"

ERR_remove_state() frees the error queue associated with the specified thread, identified by tid. ERR_remove_thread_state() does the same thing, except the identifier is an opaque pointer.

"},{"location":"man3/ERR_remove_state/#return-values","title":"RETURN VALUES","text":"

ERR_remove_state() and ERR_remove_thread_state() return no value.

"},{"location":"man3/ERR_remove_state/#see-also","title":"SEE ALSO","text":"

LOPENSSL_init_crypto(3)

"},{"location":"man3/ERR_remove_state/#history","title":"HISTORY","text":"

ERR_remove_state() was deprecated in OpenSSL 1.0.0 and ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0; these functions and should not be used.

"},{"location":"man3/ERR_remove_state/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 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.

"},{"location":"man3/ERR_set_mark/","title":"ERR_set_mark","text":""},{"location":"man3/ERR_set_mark/#name","title":"NAME","text":"

ERR_set_mark, ERR_clear_last_mark, ERR_pop_to_mark, ERR_count_to_mark, ERR_pop - set mark, clear mark, pop errors until mark and pop last error

"},{"location":"man3/ERR_set_mark/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_set_mark(void);\nint ERR_pop_to_mark(void);\nint ERR_clear_last_mark(void);\nint ERR_count_to_mark(void);\nint ERR_pop(void);\n
"},{"location":"man3/ERR_set_mark/#description","title":"DESCRIPTION","text":"

ERR_set_mark() sets a mark on the current topmost error record if there is one.

ERR_pop_to_mark() will pop the top of the error stack until a mark is found. The mark is then removed. If there is no mark, the whole stack is removed.

ERR_clear_last_mark() removes the last mark added if there is one.

ERR_count_to_mark() returns the number of entries on the error stack above the most recently marked entry, not including that entry. If there is no mark in the error stack, the number of entries in the error stack is returned.

ERR_pop() unconditionally pops a single error entry from the top of the error stack (which is the entry obtainable via ERR_peek_last_error(3)).

"},{"location":"man3/ERR_set_mark/#return-values","title":"RETURN VALUES","text":"

ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.

ERR_clear_last_mark() and ERR_pop_to_mark() return 0 if there was no mark in the error stack, which implies that the stack became empty, otherwise 1.

ERR_count_to_mark() returns the number of error stack entries found above the most recent mark, if any, or the total number of error stack entries.

ERR_pop() returns 1 if an error was popped or 0 if the error stack was empty.

"},{"location":"man3/ERR_set_mark/#history","title":"HISTORY","text":"

ERR_pop() was added in OpenSSL 3.3.

"},{"location":"man3/ERR_set_mark/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2023 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.

"},{"location":"man3/EVP_ASYM_CIPHER_free/","title":"EVP_ASYM_CIPHER_free","text":""},{"location":"man3/EVP_ASYM_CIPHER_free/#name","title":"NAME","text":"

EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref, EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_get0_provider, EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all, EVP_ASYM_CIPHER_get0_name, EVP_ASYM_CIPHER_get0_description, EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params - Functions to manage EVP_ASYM_CIPHER algorithm objects

"},{"location":"man3/EVP_ASYM_CIPHER_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                                       const char *properties);\nvoid EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher);\nint EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher);\nconst char *EVP_ASYM_CIPHER_get0_name(const EVP_ASYM_CIPHER *cipher);\nint EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name);\nOSSL_PROVIDER *EVP_ASYM_CIPHER_get0_provider(const EVP_ASYM_CIPHER *cipher);\nvoid EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,\n                                     void (*fn)(EVP_ASYM_CIPHER *cipher,\n                                                void *arg),\n                                     void *arg);\nint EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,\n                                 void (*fn)(const char *name, void *data),\n                                 void *data);\nconst char *EVP_ASYM_CIPHER_get0_description(const EVP_ASYM_CIPHER *cipher);\nconst OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip);\nconst OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip);\n
"},{"location":"man3/EVP_ASYM_CIPHER_free/#description","title":"DESCRIPTION","text":"

EVP_ASYM_CIPHER_fetch() fetches the implementation for the given algorithm from any provider offering it, within the criteria given by the properties and in the scope of the given library context ctx (see OSSL_LIB_CTX(3)). The algorithm will be one offering functions for performing asymmetric cipher related tasks such as asymmetric encryption and decryption. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_ASYM_CIPHER_free().

EVP_ASYM_CIPHER_free() decrements the reference count for the EVP_ASYM_CIPHER structure. Typically this structure will have been obtained from an earlier call to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_ASYM_CIPHER_up_ref() increments the reference count for an EVP_ASYM_CIPHER structure.

EVP_ASYM_CIPHER_is_a() returns 1 if cipher is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_ASYM_CIPHER_get0_provider() returns the provider that cipher was fetched from.

EVP_ASYM_CIPHER_do_all_provided() traverses all EVP_ASYM_CIPHERs implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_ASYM_CIPHER_get0_name() returns the algorithm name from the provided implementation for the given cipher. Note that the cipher may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the cipher object and should not be freed by the caller.

EVP_ASYM_CIPHER_names_do_all() traverses all names for cipher, and calls fn with each name and data.

EVP_ASYM_CIPHER_get0_description() returns a description of the cipher, meant for display and human consumption. The description is at the discretion of the cipher implementation.

EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set by a key encryption algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_ASYM_CIPHER_free/#return-values","title":"RETURN VALUES","text":"

EVP_ASYM_CIPHER_fetch() returns a pointer to an EVP_ASYM_CIPHER for success or NULL for failure.

EVP_ASYM_CIPHER_up_ref() returns 1 for success or 0 otherwise.

EVP_ASYM_CIPHER_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_ASYM_CIPHER_free/#see-also","title":"SEE ALSO","text":"

\"ALGORITHM FETCHING\" in crypto(7), OSSL_PROVIDER(3)

"},{"location":"man3/EVP_ASYM_CIPHER_free/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_ASYM_CIPHER_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man3/EVP_BytesToKey/","title":"EVP_BytesToKey","text":""},{"location":"man3/EVP_BytesToKey/#name","title":"NAME","text":"

EVP_BytesToKey - password based encryption routine

"},{"location":"man3/EVP_BytesToKey/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,\n                   const unsigned char *salt,\n                   const unsigned char *data, int datal, int count,\n                   unsigned char *key, unsigned char *iv);\n
"},{"location":"man3/EVP_BytesToKey/#description","title":"DESCRIPTION","text":"

EVP_BytesToKey() derives a key and IV from various parameters. type is the cipher to derive the key and IV for. md is the message digest to use. The salt parameter is used as a salt in the derivation: it should point to an 8 byte buffer or NULL if no salt is used. data is a buffer containing datal bytes which is used to derive the keying data. count is the iteration count to use. The derived key and IV will be written to key and iv respectively.

"},{"location":"man3/EVP_BytesToKey/#notes","title":"NOTES","text":"

A typical application of this function is to derive keying material for an encryption algorithm from a password in the data parameter.

Increasing the count parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords.

If the total key and IV length is less than the digest length and MD5 is used then the derivation algorithm is compatible with PKCS#5 v1.5 otherwise a non standard extension is used to derive the extra data.

Newer applications should use a more modern algorithm such as PBKDF2 as defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.

"},{"location":"man3/EVP_BytesToKey/#key-derivation-algorithm","title":"KEY DERIVATION ALGORITHM","text":"

The key and IV is derived by concatenating D_1, D_2, etc until enough data is available for the key and IV. D_i is defined as:

    D_i = HASH^count(D_(i-1) || data || salt)\n

where || denotes concatenation, D_0 is empty, HASH is the digest algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) is HASH(HASH(data)) and so on.

The initial bytes are used for the key and the subsequent bytes for the IV.

"},{"location":"man3/EVP_BytesToKey/#return-values","title":"RETURN VALUES","text":"

If data is NULL, then EVP_BytesToKey() returns the number of bytes needed to store the derived key. Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes, or 0 on error.

"},{"location":"man3/EVP_BytesToKey/#see-also","title":"SEE ALSO","text":"

evp(7), RAND_bytes(3), PKCS5_PBKDF2_HMAC(3), EVP_EncryptInit(3)

"},{"location":"man3/EVP_BytesToKey/#copyright","title":"COPYRIGHT","text":"

Copyright 2001-2016 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.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/","title":"EVP_CIPHER_CTX_get_cipher_data","text":""},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#name","title":"NAME","text":"

EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to inspect and modify EVP_CIPHER_CTX objects

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nvoid *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx);\nvoid *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data);\n
"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#description","title":"DESCRIPTION","text":"

The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the particular implementation of the cipher. For example this data can be used by engines to store engine specific information. The data is automatically allocated and freed by OpenSSL, so applications and engines should not normally free this directly (but see below).

The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to replace the cipher data with new data. A pointer to any existing cipher data is returned from this function. If the old data is no longer required then it should be freed through a call to OPENSSL_free().

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#return-values","title":"RETURN VALUES","text":"

The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current cipher data for the EVP_CIPHER_CTX.

The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old cipher data for the EVP_CIPHER_CTX.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#history","title":"HISTORY","text":"

The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data() functions were added in OpenSSL 1.1.0.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/","title":"EVP_CIPHER_CTX_get_original_iv","text":""},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#name","title":"NAME","text":"

EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv, EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv, EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);\nint EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);\nconst unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);\nunsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);\n
"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#description","title":"DESCRIPTION","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() copy initialization vector (IV) information from the EVP_CIPHER_CTX into the caller-supplied buffer. EVP_CIPHER_CTX_get_iv_length(3) can be used to determine an appropriate buffer size, and if the supplied buffer is too small, an error will be returned (and no data copied). EVP_CIPHER_CTX_get_original_iv() accesses the (\"original\") IV that was supplied when the EVP_CIPHER_CTX was initialized, and EVP_CIPHER_CTX_get_updated_iv() accesses the current \"IV state\" of the cipher, which is updated during cipher operation for certain cipher modes (e.g., CBC and OFB).

The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at a conceptual level) functionality. EVP_CIPHER_CTX_iv() returns a pointer to the beginning of the \"IV state\" as maintained internally in the EVP_CIPHER_CTX; EVP_CIPHER_CTX_original_iv() returns a pointer to the beginning of the (\"original\") IV, as maintained by the EVP_CIPHER_CTX, that was provided when the EVP_CIPHER_CTX was initialized; and EVP_CIPHER_CTX_get_iv_noconst() is the same as EVP_CIPHER_CTX_iv() but has a different return type for the pointer.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#return-values","title":"RETURN VALUES","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() return 1 on success and 0 on failure.

The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on success, and NULL on failure.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#history","title":"HISTORY","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() were added in OpenSSL 3.0.0.

EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated in OpenSSL 3.0.0.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_CIPHER_meth_new/","title":"EVP_CIPHER_meth_new","text":""},{"location":"man3/EVP_CIPHER_meth_new/#name","title":"NAME","text":"

EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods

"},{"location":"man3/EVP_CIPHER_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);\nEVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);\nvoid EVP_CIPHER_meth_free(EVP_CIPHER *cipher);\n\nint EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);\nint EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);\nint EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);\nint EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,\n                             int (*init)(EVP_CIPHER_CTX *ctx,\n                                         const unsigned char *key,\n                                         const unsigned char *iv,\n                                         int enc));\nint EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,\n                                  int (*do_cipher)(EVP_CIPHER_CTX *ctx,\n                                                   unsigned char *out,\n                                                   const unsigned char *in,\n                                                   size_t inl));\nint EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,\n                                int (*cleanup)(EVP_CIPHER_CTX *));\nint EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,\n                                        int (*set_asn1_parameters)(EVP_CIPHER_CTX *,\n                                                                   ASN1_TYPE *));\nint EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,\n                                        int (*get_asn1_parameters)(EVP_CIPHER_CTX *,\n                                                                   ASN1_TYPE *));\nint EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,\n                             int (*ctrl)(EVP_CIPHER_CTX *, int type,\n                                         int arg, void *ptr));\n\nint (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,\n                                                          const unsigned char *key,\n                                                          const unsigned char *iv,\n                                                          int enc);\nint (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,\n                                                               unsigned char *out,\n                                                               const unsigned char *in,\n                                                               size_t inl);\nint (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);\nint (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                                     ASN1_TYPE *);\nint (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                                     ASN1_TYPE *);\nint (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                          int type, int arg,\n                                                          void *ptr);\n
"},{"location":"man3/EVP_CIPHER_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the OSSL_PROVIDER APIs.

The EVP_CIPHER type is a structure for symmetric cipher method implementation.

EVP_CIPHER_meth_new() creates a new EVP_CIPHER structure.

EVP_CIPHER_meth_dup() creates a copy of cipher.

EVP_CIPHER_meth_free() destroys a EVP_CIPHER structure. If the argument is NULL, nothing is done.

EVP_CIPHER_meth_set_iv_length() sets the length of the IV. This is only needed when the implemented cipher mode requires it.

EVP_CIPHER_meth_set_flags() sets the flags to describe optional behaviours in the particular cipher. With the exception of cipher modes, of which only one may be present, several flags can be or'd together. The available flags are:

EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's implementation context so that it can be automatically allocated.

EVP_CIPHER_meth_set_init() sets the cipher init function for cipher. The cipher init function is called by EVP_CipherInit(), EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), EVP_DecryptInit(), EVP_DecryptInit_ex().

EVP_CIPHER_meth_set_do_cipher() sets the cipher function for cipher. The cipher function is called by EVP_CipherUpdate(), EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and EVP_DecryptFinal_ex().

EVP_CIPHER_meth_set_cleanup() sets the function for cipher to do extra cleanup before the method's private data structure is cleaned out and freed. Note that the cleanup function is passed a EVP_CIPHER_CTX *, the private data structure is then available with EVP_CIPHER_CTX_get_cipher_data(). This cleanup function is called by EVP_CIPHER_CTX_reset() and EVP_CIPHER_CTX_free().

EVP_CIPHER_meth_set_set_asn1_params() sets the function for cipher to set the AlgorithmIdentifier \"parameter\" based on the passed cipher. This function is called by EVP_CIPHER_param_to_asn1(). EVP_CIPHER_meth_set_get_asn1_params() sets the function for cipher that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier \"parameter\". Both these functions are needed when there is a need for custom data (more or other than the cipher IV). They are called by EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() respectively if defined.

EVP_CIPHER_meth_set_ctrl() sets the control function for cipher.

EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() are all used to retrieve the method data given with the EVP_CIPHER_meth_set_*() functions above.

"},{"location":"man3/EVP_CIPHER_meth_new/#return-values","title":"RETURN VALUES","text":"

EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a newly created EVP_CIPHER, or NULL on failure. All EVP_CIPHER_meth_set_*() functions return 1. All EVP_CIPHER_meth_get_*() functions return pointers to their respective cipher function.

"},{"location":"man3/EVP_CIPHER_meth_new/#see-also","title":"SEE ALSO","text":"

EVP_EncryptInit(3)

"},{"location":"man3/EVP_CIPHER_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0. The EVP_CIPHER structure created with these functions became reference counted in OpenSSL 3.0.

"},{"location":"man3/EVP_CIPHER_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/EVP_DigestInit/","title":"EVP_DigestInit","text":""},{"location":"man3/EVP_DigestInit/#name","title":"NAME","text":"

EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, EVP_MD_get_params, EVP_MD_gettable_params, EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_DigestSqueeze, EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, EVP_MD_CTX_get_type, EVP_MD_CTX_get_size_ex, EVP_MD_CTX_get_block_size, EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, EVP_md_null, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_do_all_provided, EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, EVP_MD_xof, EVP_MD_CTX_size, EVP_MD_CTX_get_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data - EVP digest routines

"},{"location":"man3/EVP_DigestInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                     const char *properties);\nint EVP_MD_up_ref(EVP_MD *md);\nvoid EVP_MD_free(EVP_MD *md);\nint EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest);\nEVP_MD_CTX *EVP_MD_CTX_new(void);\nint EVP_MD_CTX_reset(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_free(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);\nint EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]);\nint EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md);\nconst OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md);\nconst OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx);\nconst OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);\nvoid EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);\nint EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);\n\nint EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq,\n                 const void *data, size_t datalen,\n                 unsigned char *md, size_t *mdlen);\nint EVP_Digest(const void *data, size_t count, unsigned char *md,\n               unsigned int *size, const EVP_MD *type, ENGINE *impl);\nint EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type,\n                       const OSSL_PARAM params[]);\nint EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);\nint EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);\nint EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);\nint EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);\nint EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);\n\nEVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in);\nint EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);\n\nint EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);\nint EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);\n\nint EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);\n\nconst char *EVP_MD_get0_name(const EVP_MD *md);\nconst char *EVP_MD_get0_description(const EVP_MD *md);\nint EVP_MD_is_a(const EVP_MD *md, const char *name);\nint EVP_MD_names_do_all(const EVP_MD *md,\n                        void (*fn)(const char *name, void *data),\n                        void *data);\nconst OSSL_PROVIDER *EVP_MD_get0_provider(const EVP_MD *md);\nint EVP_MD_get_type(const EVP_MD *md);\nint EVP_MD_get_pkey_type(const EVP_MD *md);\nint EVP_MD_get_size(const EVP_MD *md);\nint EVP_MD_get_block_size(const EVP_MD *md);\nunsigned long EVP_MD_get_flags(const EVP_MD *md);\nint EVP_MD_xof(const EVP_MD *md);\n\nconst EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx);\nEVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx);\nconst char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_size_ex(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx);\nvoid *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx);\n\nconst EVP_MD *EVP_md_null(void);\n\nconst EVP_MD *EVP_get_digestbyname(const char *name);\nconst EVP_MD *EVP_get_digestbynid(int type);\nconst EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);\n\nEVP_PKEY_CTX *EVP_MD_CTX_get_pkey_ctx(const EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);\n\nvoid EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx,\n                            void (*fn)(EVP_MD *mac, void *arg),\n                            void *arg);\n\n#define EVP_MD_type EVP_MD_get_type\n#define EVP_MD_nid EVP_MD_get_type\n#define EVP_MD_name EVP_MD_get0_name\n#define EVP_MD_pkey_type EVP_MD_get_pkey_type\n#define EVP_MD_size EVP_MD_get_size\n#define EVP_MD_block_size EVP_MD_get_block_size\n#define EVP_MD_flags EVP_MD_get_flags\n#define EVP_MD_CTX_get_size EVP_MD_CTX_get_size_ex\n#define EVP_MD_CTX_size EVP_MD_CTX_get_size_ex\n#define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size\n#define EVP_MD_CTX_type EVP_MD_CTX_get_type\n#define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx\n#define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);\n\nint (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,\n                                             const void *data, size_t count);\n\nvoid EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,\n                              int (*update)(EVP_MD_CTX *ctx,\n                                            const void *data, size_t count));\n
"},{"location":"man3/EVP_DigestInit/#description","title":"DESCRIPTION","text":"

The EVP digest routines are a high-level interface to message digests, and Extendable Output Functions (XOF).

The EVP_MD type is a structure for digest method implementation.

Each Message digest algorithm (such as SHA256) produces a fixed size output length which is returned when EVP_DigestFinal_ex() is called. Extendable Output Functions (XOF) such as SHAKE256 have a variable sized output length outlen which can be used with either EVP_DigestFinalXOF() or EVP_DigestSqueeze(). EVP_DigestFinal_ex() may also be used for an XOF, but the \"xoflen\" must be set beforehand (See \"PARAMETERS\"). Note that EVP_MD_get_size() and EVP_MD_CTX_get_size_ex() behave differently for an XOF.

"},{"location":"man3/EVP_DigestInit/#parameters","title":"PARAMETERS","text":"

See OSSL_PARAM(3) for information about passing parameters.

EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:

EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:

EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:

"},{"location":"man3/EVP_DigestInit/#controls","title":"CONTROLS","text":"

EVP_MD_CTX_ctrl() can be used to send the following standard controls:

"},{"location":"man3/EVP_DigestInit/#flags","title":"FLAGS","text":"

EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags() can be used the manipulate and test these EVP_MD_CTX flags:

"},{"location":"man3/EVP_DigestInit/#return-values","title":"RETURN VALUES","text":""},{"location":"man3/EVP_DigestInit/#notes","title":"NOTES","text":"

The EVP interface to message digests should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the digest used and much more flexible.

New applications should use the SHA-2 (such as EVP_sha256(3)) or the SHA-3 digest algorithms (such as EVP_sha3_512(3)). The other digest algorithms are still in common use.

For most applications the impl parameter to EVP_DigestInit_ex() will be set to NULL to use the default digest implementation.

Ignoring failure returns of EVP_DigestInit_ex(), EVP_DigestInit_ex2(), or EVP_DigestInit() can lead to undefined behavior on subsequent calls updating or finalizing the EVP_MD_CTX such as the EVP_DigestUpdate() or EVP_DigestFinal() functions. The only valid calls on the EVP_MD_CTX when initialization fails are calls that attempt another initialization of the context or release the context.

The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are obsolete but are retained to maintain compatibility with existing code. New applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context instead of initializing and cleaning it up on each call and allow non default implementations of digests to be specified.

If digest contexts are not cleaned up after use, memory leaks will occur.

EVP_MD_CTX_get0_name(), EVP_MD_CTX_get_size(), EVP_MD_CTX_get_block_size(), EVP_MD_CTX_get_type(), EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as macros.

EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration or control.

"},{"location":"man3/EVP_DigestInit/#examples","title":"EXAMPLES","text":"

This example digests the data \"Test Message\\n\" and \"Hello World\\n\", using the digest name passed on the command line.

#include <stdio.h>\n#include <string.h>\n#include <openssl/evp.h>\n\nint main(int argc, char *argv[])\n{\n    EVP_MD_CTX *mdctx;\n    const EVP_MD *md;\n    char mess1[] = \"Test Message\\n\";\n    char mess2[] = \"Hello World\\n\";\n    unsigned char md_value[EVP_MAX_MD_SIZE];\n    unsigned int md_len, i;\n\n    if (argv[1] == NULL) {\n        printf(\"Usage: mdtest digestname\\n\");\n        exit(1);\n    }\n\n    md = EVP_get_digestbyname(argv[1]);\n    if (md == NULL) {\n        printf(\"Unknown message digest %s\\n\", argv[1]);\n        exit(1);\n    }\n\n    mdctx = EVP_MD_CTX_new();\n    if (mdctx == NULL) {\n       printf(\"Message digest create failed.\\n\");\n       exit(1);\n    }\n    if (!EVP_DigestInit_ex2(mdctx, md, NULL)) {\n        printf(\"Message digest initialization failed.\\n\");\n        EVP_MD_CTX_free(mdctx);\n        exit(1);\n    }\n    if (!EVP_DigestUpdate(mdctx, mess1, strlen(mess1))) {\n        printf(\"Message digest update failed.\\n\");\n        EVP_MD_CTX_free(mdctx);\n        exit(1);\n    }\n    if (!EVP_DigestUpdate(mdctx, mess2, strlen(mess2))) {\n        printf(\"Message digest update failed.\\n\");\n        EVP_MD_CTX_free(mdctx);\n        exit(1);\n    }\n    if (!EVP_DigestFinal_ex(mdctx, md_value, &md_len)) {\n        printf(\"Message digest finalization failed.\\n\");\n        EVP_MD_CTX_free(mdctx);\n        exit(1);\n    }\n    EVP_MD_CTX_free(mdctx);\n\n    printf(\"Digest is: \");\n    for (i = 0; i < md_len; i++)\n        printf(\"%02x\", md_value[i]);\n    printf(\"\\n\");\n\n    exit(0);\n}\n
"},{"location":"man3/EVP_DigestInit/#see-also","title":"SEE ALSO","text":"

EVP_MD_meth_new(3), openssl-dgst(1), evp(7), OSSL_PROVIDER(3), OSSL_PARAM(3), property(7), \"ALGORITHM FETCHING\" in crypto(7), provider-digest(7), life_cycle-digest(7)

The full list of digest algorithms are provided below.

EVP_blake2b512(3), EVP_md2(3), EVP_md4(3), EVP_md5(3), EVP_mdc2(3), EVP_ripemd160(3), EVP_sha1(3), EVP_sha224(3), EVP_sha3_224(3), EVP_sm3(3), EVP_whirlpool(3)

"},{"location":"man3/EVP_DigestInit/#history","title":"HISTORY","text":"

The EVP_MD_CTX_create() and EVP_MD_CTX_destroy() functions were renamed to EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0, respectively.

The link between digests and signing algorithms was fixed in OpenSSL 1.0 and later, so now EVP_sha1() can be used with RSA and DSA.

The EVP_dss1() function was removed in OpenSSL 1.1.0.

The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1.

The EVP_Q_digest(), EVP_DigestInit_ex2(), EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_get_params(), EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(), EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and EVP_MD_CTX_gettable_params() functions were added in OpenSSL 3.0.

The EVP_MD_type(), EVP_MD_nid(), EVP_MD_name(), EVP_MD_pkey_type(), EVP_MD_size(), EVP_MD_block_size(), EVP_MD_flags(), EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), and EVP_MD_CTX_md_data() functions were renamed to include get or get0 in their names in OpenSSL 3.0, respectively. The old names are kept as non-deprecated alias macros.

The EVP_MD_CTX_md() function was deprecated in OpenSSL 3.0; use EVP_MD_CTX_get0_md() instead. EVP_MD_CTX_update_fn() and EVP_MD_CTX_set_update_fn() were deprecated in OpenSSL 3.0.

The EVP_MD_CTX_dup() function was added in OpenSSL 3.1.

The EVP_DigestSqueeze() function was added in OpenSSL 3.3.

The EVP_MD_CTX_get_size_ex() and EVP_xof() functions were added in OpenSSL 3.4. The macros EVP_MD_CTX_get_size() and EVP_MD_CTX_size were changed in OpenSSL 3.4 to be aliases for EVP_MD_CTX_get_size_ex(), previously they were aliases for EVP_MD_get_size which returned a constant value. This is required for XOF digests since they do not have a fixed size.

"},{"location":"man3/EVP_DigestInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/EVP_DigestSignInit/","title":"EVP_DigestSignInit","text":""},{"location":"man3/EVP_DigestSignInit/#name","title":"NAME","text":"

EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions

"},{"location":"man3/EVP_DigestSignInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,\n                          const char *mdname, OSSL_LIB_CTX *libctx,\n                          const char *props, EVP_PKEY *pkey,\n                          const OSSL_PARAM params[]);\nint EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,\n                       const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);\nint EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);\nint EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);\n\nint EVP_DigestSign(EVP_MD_CTX *ctx, unsigned char *sig,\n                   size_t *siglen, const unsigned char *tbs,\n                   size_t tbslen);\n
"},{"location":"man3/EVP_DigestSignInit/#description","title":"DESCRIPTION","text":"

The EVP signature routines are a high-level interface to digital signatures. Input data is digested first before the signing takes place.

EVP_DigestSignInit_ex() sets up signing context ctx to use a digest with the name mdname and private key pkey. The name of the digest to be used is passed to the provider of the signature algorithm in use. How that provider interprets the digest name is provider specific. The provider may implement that digest directly itself or it may (optionally) choose to fetch it (which could result in a digest from a different provider being selected). If the provider supports fetching the digest then it may use the props argument for the properties to be used during the fetch. Finally, the passed parameters params, if not NULL, are set on the context before returning.

The pkey algorithm is used to fetch a EVP_SIGNATURE method implicitly, to be used for the actual signing. See \"Implicit fetch\" in provider(7) for more information about implicit fetches.

The OpenSSL default and legacy providers support fetching digests and can fetch those digests from any available provider. The OpenSSL FIPS provider also supports fetching digests but will only fetch digests that are themselves implemented inside the FIPS provider.

ctx must be created with EVP_MD_CTX_new() before calling this function. If pctx is not NULL, the EVP_PKEY_CTX of the signing operation will be written to *pctx: this can be used to set alternative signing options. Note that any existing value in *pctx is overwritten. The EVP_PKEY_CTX value returned must not be freed directly by the application if ctx is not assigned an EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_ex() (which means the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be used is created by EVP_DigestSignInit_ex then it will use the OSSL_LIB_CTX specified in libctx and the property query string specified in props.

The digest mdname may be NULL if the signing algorithm supports it. The props argument can always be NULL.

No EVP_PKEY_CTX will be created by EVP_DigestSignInit_ex() if the passed ctx has already been assigned one via EVP_MD_CTX_set_pkey_ctx(3). See also SM2(7).

Only EVP_PKEY types that support signing can be used with these functions. This includes MAC algorithms where the MAC generation is considered as a form of \"signing\". Built-in EVP_PKEY types supported by these functions are CMAC, Poly1305, DSA, ECDSA, HMAC, RSA, SipHash, Ed25519 and Ed448.

Not all digests can be used for all key types. The following combinations apply.

If RSA-PSS is used and restrictions apply then the digest must match.

EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex() except that the mdname parameter will be inferred from the supplied digest type, and props will be NULL. Where supplied the ENGINE e will be used for the signing and digest algorithm implementations. e may be NULL.

EVP_DigestSignUpdate() hashes cnt bytes of data at d into the signature context ctx. This function can be called several times on the same ctx to include additional data. ctx MUST NOT be NULL.

Unless sig is NULL EVP_DigestSignFinal() signs the data in ctx and places the signature in sig. Otherwise the maximum necessary size of the output buffer is written to the siglen parameter. If sig is not NULL then before the call the siglen parameter should contain the length of the sig buffer. If the call is successful the signature is written to sig and the amount of data written to siglen.

EVP_DigestSign() is similar to a single call to EVP_DigestSignUpdate() and EVP_DigestSignFinal(). Unless sig is NULL, EVP_DigestSign() signs the data tbs of length tbslen bytes and places the signature in a buffer sig of size siglen. If sig is NULL, the maximum necessary size of the signature buffer is written to the siglen parameter.

"},{"location":"man3/EVP_DigestSignInit/#return-values","title":"RETURN VALUES","text":"

EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignFinal() and EVP_DigestSign() return 1 for success and 0 for failure.

The error codes can be obtained from ERR_get_error(3).

"},{"location":"man3/EVP_DigestSignInit/#notes","title":"NOTES","text":"

The EVP interface to digital signatures should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible.

EVP_DigestSign() is a one shot operation which signs a single block of data in one function. For algorithms that support streaming it is equivalent to calling EVP_DigestSignUpdate() and EVP_DigestSignFinal(). For algorithms which do not support streaming (e.g. PureEdDSA) it is the only way to sign data.

In previous versions of OpenSSL there was a link between message digest types and public key algorithms. This meant that \"clone\" digests such as EVP_dss1() needed to be used to sign using SHA1 and DSA. This is no longer necessary and the use of clone digest is now discouraged.

For some key types and parameters the random number generator must be seeded. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

The call to EVP_DigestSignFinal() internally finalizes a copy of the digest context. This means that calls to EVP_DigestSignUpdate() and EVP_DigestSignFinal() can be called later to digest and sign additional data. Applications may disable this behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via EVP_MD_CTX_set_flags(3).

Note that not all providers support continuation, in case the selected provider does not allow to duplicate contexts EVP_DigestSignFinal() will finalize the digest context and attempting to process additional data via EVP_DigestSignUpdate() will result in an error.

EVP_DigestSignInit() and EVP_DigestSignInit_ex() functions can be called multiple times on a context and the parameters set by previous calls should be preserved if the pkey parameter is NULL. The call then just resets the state of the ctx.

EVP_DigestSign() can not be called again, once a signature is generated (by passing sig as non NULL), unless the EVP_MD_CTX is reinitialised by calling EVP_DigestSignInit_ex().

Ignoring failure returns of EVP_DigestSignInit() and EVP_DigestSignInit_ex() functions can lead to subsequent undefined behavior when calling EVP_DigestSignUpdate(), EVP_DigestSignFinal(), or EVP_DigestSign().

The use of EVP_PKEY_get_size() with these functions is discouraged because some signature operations may have a signature length which depends on the parameters set. As a result EVP_PKEY_get_size() would have to return a value which indicates the maximum possible signature for any set of parameters.

"},{"location":"man3/EVP_DigestSignInit/#see-also","title":"SEE ALSO","text":"

EVP_DigestVerifyInit(3), EVP_DigestInit(3), evp(7), HMAC(3), MD2(3), MD5(3), MDC2(3), RIPEMD160(3), SHA1(3), openssl-dgst(1), RAND(7)

"},{"location":"man3/EVP_DigestSignInit/#history","title":"HISTORY","text":"

EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() were added in OpenSSL 1.0.0.

EVP_DigestSignInit_ex() was added in OpenSSL 3.0.

EVP_DigestSignUpdate() was converted from a macro to a function in OpenSSL 3.0.

"},{"location":"man3/EVP_DigestSignInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_DigestVerifyInit/","title":"EVP_DigestVerifyInit","text":""},{"location":"man3/EVP_DigestVerifyInit/#name","title":"NAME","text":"

EVP_DigestVerifyInit_ex, EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal, EVP_DigestVerify - EVP signature verification functions

"},{"location":"man3/EVP_DigestVerifyInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,\n                            const char *mdname, OSSL_LIB_CTX *libctx,\n                            const char *props, EVP_PKEY *pkey,\n                            const OSSL_PARAM params[]);\nint EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,\n                         const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);\nint EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);\nint EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig,\n                          size_t siglen);\nint EVP_DigestVerify(EVP_MD_CTX *ctx, const unsigned char *sig,\n                     size_t siglen, const unsigned char *tbs, size_t tbslen);\n
"},{"location":"man3/EVP_DigestVerifyInit/#description","title":"DESCRIPTION","text":"

The EVP signature routines are a high-level interface to digital signatures. Input data is digested first before the signature verification takes place.

EVP_DigestVerifyInit_ex() sets up verification context ctx to use a digest with the name mdname and public key pkey. The name of the digest to be used is passed to the provider of the signature algorithm in use. How that provider interprets the digest name is provider specific. The provider may implement that digest directly itself or it may (optionally) choose to fetch it (which could result in a digest from a different provider being selected). If the provider supports fetching the digest then it may use the props argument for the properties to be used during the fetch. Finally, the passed parameters params, if not NULL, are set on the context before returning.

The pkey algorithm is used to fetch a EVP_SIGNATURE method implicitly, to be used for the actual signing. See \"Implicit fetch\" in provider(7) for more information about implicit fetches.

The OpenSSL default and legacy providers support fetching digests and can fetch those digests from any available provider. The OpenSSL FIPS provider also supports fetching digests but will only fetch digests that are themselves implemented inside the FIPS provider.

ctx must be created with EVP_MD_CTX_new() before calling this function. If pctx is not NULL, the EVP_PKEY_CTX of the verification operation will be written to *pctx: this can be used to set alternative verification options. Note that any existing value in *pctx is overwritten. The EVP_PKEY_CTX value returned must not be freed directly by the application if ctx is not assigned an EVP_PKEY_CTX value before being passed to EVP_DigestVerifyInit_ex() (which means the EVP_PKEY_CTX is created inside EVP_DigestVerifyInit_ex() and it will be freed automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be used is created by EVP_DigestVerifyInit_ex then it will use the OSSL_LIB_CTX specified in libctx and the property query string specified in props.

No EVP_PKEY_CTX will be created by EVP_DigestVerifyInit_ex() if the passed ctx has already been assigned one via EVP_MD_CTX_set_pkey_ctx(3). See also SM2(7).

Not all digests can be used for all key types. The following combinations apply.

If RSA-PSS is used and restrictions apply then the digest must match.

EVP_DigestVerifyInit() works in the same way as EVP_DigestVerifyInit_ex() except that the mdname parameter will be inferred from the supplied digest type, and props will be NULL. Where supplied the ENGINE e will be used for the signature verification and digest algorithm implementations. e may be NULL.

EVP_DigestVerifyUpdate() hashes cnt bytes of data at d into the verification context ctx. This function can be called several times on the same ctx to include additional data.

EVP_DigestVerifyFinal() verifies the data in ctx against the signature in sig of length siglen.

EVP_DigestVerify() verifies tbslen bytes at tbs against the signature in sig of length siglen.

"},{"location":"man3/EVP_DigestVerifyInit/#return-values","title":"RETURN VALUES","text":"

EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 for failure.

EVP_DigestVerifyFinal() and EVP_DigestVerify() return 1 for success; any other value indicates failure. A return value of zero indicates that the signature did not verify successfully (that is, tbs did not match the original data or the signature had an invalid form), while other values indicate a more serious error (and sometimes also indicate an invalid signature form).

The error codes can be obtained from ERR_get_error(3).

"},{"location":"man3/EVP_DigestVerifyInit/#notes","title":"NOTES","text":"

The EVP interface to digital signatures should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible.

EVP_DigestVerify() is a one shot operation which verifies a single block of data in one function. For algorithms that support streaming it is equivalent to calling EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal(). For algorithms which do not support streaming (e.g. PureEdDSA) it is the only way to verify data.

In previous versions of OpenSSL there was a link between message digest types and public key algorithms. This meant that \"clone\" digests such as EVP_dss1() needed to be used to sign using SHA1 and DSA. This is no longer necessary and the use of clone digest is now discouraged.

For some key types and parameters the random number generator must be seeded. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data. Applications may disable this behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via EVP_MD_CTX_set_flags(3).

Note that not all providers support continuation, in case the selected provider does not allow to duplicate contexts EVP_DigestVerifyFinal() will finalize the digest context and attempting to process additional data via EVP_DigestVerifyUpdate() will result in an error.

EVP_DigestVerifyInit() and EVP_DigestVerifyInit_ex() functions can be called multiple times on a context and the parameters set by previous calls should be preserved if the pkey parameter is NULL. The call then just resets the state of the ctx.

EVP_DigestVerify() can only be called once, and cannot be used again without reinitialising the EVP_MD_CTX by calling EVP_DigestVerifyInit_ex().

Ignoring failure returns of EVP_DigestVerifyInit() and EVP_DigestVerifyInit_ex() functions can lead to subsequent undefined behavior when calling EVP_DigestVerifyUpdate(), EVP_DigestVerifyFinal(), or EVP_DigestVerify().

"},{"location":"man3/EVP_DigestVerifyInit/#see-also","title":"SEE ALSO","text":"

EVP_DigestSignInit(3), EVP_DigestInit(3), evp(7), HMAC(3), MD2(3), MD5(3), MDC2(3), RIPEMD160(3), SHA1(3), openssl-dgst(1), RAND(7)

"},{"location":"man3/EVP_DigestVerifyInit/#history","title":"HISTORY","text":"

EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() were added in OpenSSL 1.0.0.

EVP_DigestVerifyInit_ex() was added in OpenSSL 3.0.

EVP_DigestVerifyUpdate() was converted from a macro to a function in OpenSSL 3.0.

"},{"location":"man3/EVP_DigestVerifyInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_EncodeInit/","title":"EVP_EncodeInit","text":""},{"location":"man3/EVP_EncodeInit/#name","title":"NAME","text":"

EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, EVP_DecodeBlock - EVP base64 encode/decode routines

"},{"location":"man3/EVP_EncodeInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void);\nvoid EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx);\nint EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx);\nint EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx);\nvoid EVP_EncodeInit(EVP_ENCODE_CTX *ctx);\nint EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,\n                     const unsigned char *in, int inl);\nvoid EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl);\nint EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n);\n\nvoid EVP_DecodeInit(EVP_ENCODE_CTX *ctx);\nint EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,\n                     const unsigned char *in, int inl);\nint EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl);\nint EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n);\n
"},{"location":"man3/EVP_EncodeInit/#description","title":"DESCRIPTION","text":"

The EVP encode routines provide a high-level interface to base64 encoding and decoding. Base64 encoding converts binary data into a printable form that uses the characters A-Z, a-z, 0-9, \"+\" and \"/\" to represent the data. For every 3 bytes of binary data provided 4 bytes of base64 encoded data will be produced plus some occasional newlines (see below). If the input data length is not a multiple of 3 then the output data will be padded at the end using the \"=\" character.

EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for the encode/decode functions.

EVP_ENCODE_CTX_free() cleans up an encode/decode context ctx and frees up the space allocated to it. If the argument is NULL, nothing is done.

Encoding of binary data is performed in blocks of 48 input bytes (or less for the final block). For each 48 byte input block encoded 64 bytes of base64 data is output plus an additional newline character (i.e. 65 bytes in total). The final block (which may be less than 48 bytes) will output 4 bytes for every 3 bytes of input. If the data length is not divisible by 3 then a full 4 bytes is still output for the final 1 or 2 bytes of input. Similarly a newline character will also be output.

EVP_EncodeInit() initialises ctx for the start of a new encoding operation.

EVP_EncodeUpdate() encode inl bytes of data found in the buffer pointed to by in. The output is stored in the buffer out and the number of bytes output is stored in *outl. It is the caller's responsibility to ensure that the buffer at out is sufficiently large to accommodate the output data. Only full blocks of data (48 bytes) will be immediately processed and output by this function. Any remainder is held in the ctx object and will be processed by a subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the required size of the output buffer add together the value of inl with the amount of unprocessed data held in ctx and divide the result by 48 (ignore any remainder). This gives the number of blocks of data that will be processed. Ensure the output buffer contains 65 bytes of storage for each block, plus an additional byte for a NUL terminator. EVP_EncodeUpdate() may be called repeatedly to process large amounts of input data. In the event of an error EVP_EncodeUpdate() will set *outl to 0 and return 0. On success 1 will be returned.

EVP_EncodeFinal() must be called at the end of an encoding operation. It will process any partial block of data remaining in the ctx object. The output data will be stored in out and the length of the data written will be stored in *outl. It is the caller's responsibility to ensure that out is sufficiently large to accommodate the output data which will never be more than 65 bytes plus an additional NUL terminator (i.e. 66 bytes in total).

EVP_ENCODE_CTX_copy() can be used to copy a context sctx to a context dctx. dctx must be initialized before calling this function.

EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to be encoded or decoded that are pending in the ctx object.

EVP_EncodeBlock() encodes a full block of input data in f and of length n and stores it in t. For every 3 bytes of input provided 4 bytes of output data will be produced. If n is not divisible by 3 then the block is encoded as a final block of data and the output is padded such that it is always divisible by 4. Additionally a NUL terminator character will be added. For example if 16 bytes of input data is provided then 24 bytes of encoded data is created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of the data generated without the NUL terminator is returned from the function.

EVP_DecodeInit() initialises ctx for the start of a new decoding operation.

EVP_DecodeUpdate() decodes inl characters of data found in the buffer pointed to by in. The output is stored in the buffer out and the number of bytes output is stored in *outl. It is the caller's responsibility to ensure that the buffer at out is sufficiently large to accommodate the output data. This function will attempt to decode as much data as possible in chunks of up to 80 base64 characters at a time. Residual input shorter than the internal chunk size will be buffered in ctx if its length is not a multiple of 4 (including any padding), to be processed in future calls to EVP_DecodeUpdate() or EVP_DecodeFinal(). If the final chunk length is a multiple of 4, it is decoded immediately and not buffered.

Any whitespace, newline or carriage return characters are ignored. For compatibility with PEM, the - (hyphen) character is treated as a soft end-of-input, subsequent bytes are not buffered, and the return value will be 0 to indicate that the end of the base64 input has been detected. The soft end-of-input, if present, MUST occur after a multiple of 4 valid base64 input bytes. The soft end-of-input condition is not remembered in ctx, it is up to the caller to avoid further calls to EVP_DecodeUpdate() after a 0 or negative (error) return.

If any invalid base64 characters are encountered or if the base64 padding character (=) is encountered in the middle of the data then EVP_DecodeUpdate() returns -1 to indicate an error. A return value of 0 or 1 indicates successful processing of the data. A return value of 0 additionally indicates that the last 4 bytes processed ended with base64 padding (=), or that the next 4 byte group starts with the soft end-of-input (-) character, and therefore no more input data is expected to be processed.

For every 4 valid base64 bytes processed (ignoring whitespace, carriage returns and line feeds), 3 bytes of binary output data will be produced (except at the end of data terminated with one or two padding characters).

EVP_DecodeFinal() should be called at the end of a decoding operation, but it will never decode additional data. If there is no residual data it will return 1 to indicate success. If there is residual data, its length is not a multiple of 4, i.e. it was not properly padded, -1 is is returned in that case to indicate an error.

EVP_DecodeBlock() will decode the block of n characters of base64 data contained in f and store the result in t. Any leading whitespace will be trimmed as will any trailing whitespace, newlines, carriage returns or EOF characters. Internal whitespace MUST NOT be present. After trimming the data in f MUST consist entirely of valid base64 characters or padding (only at the tail of the input) and its length MUST be divisible by 4. For every 4 input bytes exactly 3 output bytes will be produced. Padding bytes (=) (even if internal) are decoded to 6 zero bits, the caller is responsible for taking trailing padding into account, by ignoring as many bytes at the tail of the returned output. EVP_DecodeBlock() will return the length of the data decoded or -1 on error.

"},{"location":"man3/EVP_EncodeInit/#return-values","title":"RETURN VALUES","text":"

EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX object or NULL on error.

EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in ctx.

EVP_EncodeUpdate() returns 0 on error or 1 on success.

EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL terminator.

EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned then no more non-padding base64 characters are expected.

EVP_DecodeFinal() returns -1 on error or 1 on success.

EVP_DecodeBlock() returns the length of the data decoded or -1 on error.

"},{"location":"man3/EVP_EncodeInit/#see-also","title":"SEE ALSO","text":"

evp(7)

"},{"location":"man3/EVP_EncodeInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/EVP_EncryptInit/","title":"EVP_EncryptInit","text":""},{"location":"man3/EVP_EncryptInit/#name","title":"NAME","text":"

EVP_CIPHER_fetch, EVP_CIPHER_up_ref, EVP_CIPHER_free, EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, EVP_CIPHER_CTX_dup, EVP_CIPHER_CTX_copy, EVP_EncryptInit_ex, EVP_EncryptInit_ex2, EVP_EncryptUpdate, EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptInit_ex2, EVP_DecryptUpdate, EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherInit_ex2, EVP_CipherUpdate, EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit, EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_Cipher, EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_is_a, EVP_CIPHER_get0_name, EVP_CIPHER_get0_description, EVP_CIPHER_names_do_all, EVP_CIPHER_get0_provider, EVP_CIPHER_get_nid, EVP_CIPHER_get_params, EVP_CIPHER_gettable_params, EVP_CIPHER_get_block_size, EVP_CIPHER_get_key_length, EVP_CIPHER_get_iv_length, EVP_CIPHER_get_flags, EVP_CIPHER_get_mode, EVP_CIPHER_get_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_get0_cipher, EVP_CIPHER_CTX_get1_cipher, EVP_CIPHER_CTX_get0_name, EVP_CIPHER_CTX_get_nid, EVP_CIPHER_CTX_get_params, EVP_CIPHER_gettable_ctx_params, EVP_CIPHER_CTX_gettable_params, EVP_CIPHER_CTX_set_params, EVP_CIPHER_settable_ctx_params, EVP_CIPHER_CTX_settable_params, EVP_CIPHER_CTX_get_block_size, EVP_CIPHER_CTX_get_key_length, EVP_CIPHER_CTX_get_iv_length, EVP_CIPHER_CTX_get_tag_length, EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_set_flags, EVP_CIPHER_CTX_clear_flags, EVP_CIPHER_CTX_test_flags, EVP_CIPHER_CTX_get_type, EVP_CIPHER_CTX_get_mode, EVP_CIPHER_CTX_get_num, EVP_CIPHER_CTX_set_num, EVP_CIPHER_CTX_is_encrypting, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_CIPHER_do_all_provided, EVP_CIPHER_nid, EVP_CIPHER_name, EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_encrypting, EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_tag_length, EVP_CIPHER_CTX_num, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_mode - EVP cipher routines

"},{"location":"man3/EVP_EncryptInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                             const char *properties);\nint EVP_CIPHER_up_ref(EVP_CIPHER *cipher);\nvoid EVP_CIPHER_free(EVP_CIPHER *cipher);\nEVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);\nint EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);\nvoid EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);\nEVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);\nint EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);\n\nint EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                       ENGINE *impl, const unsigned char *key, const unsigned char *iv);\nint EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                        const unsigned char *key, const unsigned char *iv,\n                        const OSSL_PARAM params[]);\nint EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,\n                      int *outl, const unsigned char *in, int inl);\nint EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);\n\nint EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                       ENGINE *impl, const unsigned char *key, const unsigned char *iv);\nint EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                        const unsigned char *key, const unsigned char *iv,\n                        const OSSL_PARAM params[]);\nint EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,\n                      int *outl, const unsigned char *in, int inl);\nint EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);\n\nint EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                      ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);\nint EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                       const unsigned char *key, const unsigned char *iv,\n                       int enc, const OSSL_PARAM params[]);\nint EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,\n                     int *outl, const unsigned char *in, int inl);\nint EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);\n\nint EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                    const unsigned char *key, const unsigned char *iv);\nint EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);\n\nint EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                    const unsigned char *key, const unsigned char *iv);\nint EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);\n\nint EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                   const unsigned char *key, const unsigned char *iv, int enc);\nint EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);\n\nint EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out,\n               const unsigned char *in, unsigned int inl);\n\nint EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);\nint EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);\nint EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2);\nint EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);\nvoid EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags);\nvoid EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags);\nint EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags);\n\nconst EVP_CIPHER *EVP_get_cipherbyname(const char *name);\nconst EVP_CIPHER *EVP_get_cipherbynid(int nid);\nconst EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);\n\nint EVP_CIPHER_get_nid(const EVP_CIPHER *e);\nint EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);\nint EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,\n                            void (*fn)(const char *name, void *data),\n                            void *data);\nconst char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher);\nconst char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher);\nconst OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher);\nint EVP_CIPHER_get_block_size(const EVP_CIPHER *e);\nint EVP_CIPHER_get_key_length(const EVP_CIPHER *e);\nint EVP_CIPHER_get_iv_length(const EVP_CIPHER *e);\nunsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e);\nunsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e);\nint EVP_CIPHER_get_type(const EVP_CIPHER *cipher);\n\nconst EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx);\nEVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx);\nconst char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx);\n\nint EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]);\nint EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);\nconst OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher);\nconst OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher);\nconst OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx);\nconst OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx);\nvoid *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);\nvoid EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);\nint EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);\nint EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);\nint EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx);\n\nint EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);\nint EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);\n\nvoid EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,\n                                void (*fn)(EVP_CIPHER *cipher, void *arg),\n                                void *arg);\n\n#define EVP_CIPHER_nid EVP_CIPHER_get_nid\n#define EVP_CIPHER_name EVP_CIPHER_get0_name\n#define EVP_CIPHER_block_size EVP_CIPHER_get_block_size\n#define EVP_CIPHER_key_length EVP_CIPHER_get_key_length\n#define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length\n#define EVP_CIPHER_flags EVP_CIPHER_get_flags\n#define EVP_CIPHER_mode EVP_CIPHER_get_mode\n#define EVP_CIPHER_type EVP_CIPHER_get_type\n#define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting\n#define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid\n#define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size\n#define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length\n#define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length\n#define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length\n#define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num\n#define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type\n#define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx);\n
"},{"location":"man3/EVP_EncryptInit/#description","title":"DESCRIPTION","text":"

The EVP cipher routines are a high-level interface to certain symmetric ciphers.

The EVP_CIPHER type is a structure for cipher method implementation.

"},{"location":"man3/EVP_EncryptInit/#parameters","title":"PARAMETERS","text":"

See OSSL_PARAM(3) for information about passing parameters.

"},{"location":"man3/EVP_EncryptInit/#gettable-evp_cipher-parameters","title":"Gettable EVP_CIPHER parameters","text":"

When EVP_CIPHER_fetch() is called it internally calls EVP_CIPHER_get_params() and caches the results.

EVP_CIPHER_get_params() can be used with the following OSSL_PARAM(3) keys:

"},{"location":"man3/EVP_EncryptInit/#gettable-and-settable-evp_cipher_ctx-parameters","title":"Gettable and Settable EVP_CIPHER_CTX parameters","text":"

The following OSSL_PARAM(3) keys can be used with both EVP_CIPHER_CTX_get_params() and EVP_CIPHER_CTX_set_params().

"},{"location":"man3/EVP_EncryptInit/#gettable-evp_cipher_ctx-parameters","title":"Gettable EVP_CIPHER_CTX parameters","text":"

The following OSSL_PARAM(3) keys can be used with EVP_CIPHER_CTX_get_params():

"},{"location":"man3/EVP_EncryptInit/#settable-evp_cipher_ctx-parameters","title":"Settable EVP_CIPHER_CTX parameters","text":"

The following OSSL_PARAM(3) keys can be used with EVP_CIPHER_CTX_set_params():

"},{"location":"man3/EVP_EncryptInit/#controls","title":"CONTROLS","text":"

The Mappings from EVP_CIPHER_CTX_ctrl() identifiers to PARAMETERS are listed in the following section. See the \"PARAMETERS\" section for more details.

EVP_CIPHER_CTX_ctrl() can be used to send the following standard controls:

"},{"location":"man3/EVP_EncryptInit/#flags","title":"FLAGS","text":"

EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags(). can be used to manipulate and test these EVP_CIPHER_CTX flags:

EVP_CIPHER_flags() uses the following flags that have mappings to \"Gettable EVP_CIPHER parameters\":

EVP_CIPHER_flags() uses the following flags for legacy purposes only:

"},{"location":"man3/EVP_EncryptInit/#return-values","title":"RETURN VALUES","text":"

EVP_CIPHER_fetch() returns a pointer to a EVP_CIPHER for success and NULL for failure.

EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.

EVP_CIPHER_CTX_new() returns a pointer to a newly created EVP_CIPHER_CTX for success and NULL for failure.

EVP_CIPHER_CTX_dup() returns a new EVP_CIPHER_CTX if successful or NULL on failure.

EVP_CIPHER_CTX_copy() returns 1 if successful or 0 for failure.

EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() return 1 for success and 0 for failure.

EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and 0 for failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.

EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for failure. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.

EVP_Cipher() returns 1 on success and <= 0 on failure, if the flag EVP_CIPH_FLAG_CUSTOM_CIPHER is not set for the cipher, or if the cipher has not been initialized via a call to EVP_CipherInit_ex2. EVP_Cipher() returns the number of bytes written to out for encryption / decryption, or the number of bytes authenticated in a call specifying AAD for an AEAD cipher, if the flag EVP_CIPH_FLAG_CUSTOM_CIPHER is set for the cipher.

EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.

EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an EVP_CIPHER structure or NULL on error.

EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() return a NID.

EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() return the block size, or 0 on error.

EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() return the key length.

EVP_CIPHER_CTX_set_padding() always returns 1.

EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() return the IV length, zero if the cipher does not use an IV and a negative value on error.

EVP_CIPHER_CTX_get_tag_length() return the tag length or zero if the cipher does not use a tag.

EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() return the NID of the cipher's OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.

EVP_CIPHER_CTX_cipher() returns an EVP_CIPHER structure.

EVP_CIPHER_CTX_get_num() returns a nonnegative num value or EVP_CTRL_RET_UNSUPPORTED if the implementation does not support the call or on any other error.

EVP_CIPHER_CTX_set_num() returns 1 on success and 0 if the implementation does not support the call or on any other error.

EVP_CIPHER_CTX_is_encrypting() returns 1 if the ctx is set up for encryption 0 otherwise.

EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater than zero for success and zero or a negative number on failure.

EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative number for failure.

EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

"},{"location":"man3/EVP_EncryptInit/#cipher-listing","title":"CIPHER LISTING","text":"

All algorithms have a fixed key length unless otherwise stated.

Refer to \"SEE ALSO\" for the full list of ciphers available through the EVP interface.

"},{"location":"man3/EVP_EncryptInit/#aead-interface","title":"AEAD INTERFACE","text":"

The EVP interface for Authenticated Encryption with Associated Data (AEAD) modes are subtly altered and several additional ctrl operations are supported depending on the mode specified.

To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output parameter out set to NULL. In this case, on success, the parameter outl is set to the number of bytes authenticated.

When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal() indicates whether the operation was successful. If it does not indicate success, the authentication operation has failed and any output data MUST NOT be used as it is corrupted.

Please note that the number of authenticated bytes returned by EVP_CipherUpdate() depends on the cipher used. Stream ciphers, such as ChaCha20 or ciphers in GCM mode, can handle 1 byte at a time, resulting in an effective \"block\" size of 1. Conversely, ciphers in OCB mode must process data one block at a time, and the block size is returned.

Regardless of the returned size, it is safe to pass unpadded data to an EVP_CipherUpdate() call in a single operation.

"},{"location":"man3/EVP_EncryptInit/#gcm-and-ocb-modes","title":"GCM and OCB Modes","text":"

The following _ctrl_s are supported in GCM and OCB modes.

"},{"location":"man3/EVP_EncryptInit/#ccm-mode","title":"CCM Mode","text":"

The EVP interface for CCM mode is similar to that of the GCM mode but with a few additional requirements and different ctrl values.

For CCM mode, the total plaintext or ciphertext length MUST be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output and input parameters (in and out) set to NULL and the length passed in the inl parameter.

The following _ctrl_s are supported in CCM mode.

"},{"location":"man3/EVP_EncryptInit/#siv-mode","title":"SIV Mode","text":"

Both the AES-SIV and AES-GCM-SIV ciphers fall under this mode.

For SIV mode ciphers the behaviour of the EVP interface is subtly altered and several additional ctrl operations are supported.

To specify any additional authenticated data (AAD) and/or a Nonce, a call to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output parameter out set to NULL.

RFC5297 states that the Nonce is the last piece of AAD before the actual encrypt/decrypt takes place. The API does not differentiate the Nonce from other AAD.

When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() indicates if the operation was successful. If it does not indicate success the authentication operation has failed and any output data MUST NOT be used as it is corrupted.

The API does not store the SIV (Synthetic Initialization Vector) in the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX. The SIV must be retrieved from the context after encryption, and set into the context before decryption.

This differs from RFC5297 in that the cipher output from encryption, and the cipher input to decryption, does not contain the SIV. This also means that the plain text and cipher text lengths are identical.

The following ctrls are supported in SIV mode, and are used to get and set the Synthetic Initialization Vector:

SIV mode makes two passes over the input data, thus, only one call to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with out set to a non-NULL value. A call to EVP_DecryptFinal() or EVP_CipherFinal() is not required, but will indicate if the update operation succeeded.

"},{"location":"man3/EVP_EncryptInit/#chacha20-poly1305","title":"ChaCha20-Poly1305","text":"

The following _ctrl_s are supported for the ChaCha20-Poly1305 AEAD algorithm.

"},{"location":"man3/EVP_EncryptInit/#notes","title":"NOTES","text":"

Where possible the EVP interface to symmetric ciphers should be used in preference to the low-level interfaces. This is because the code then becomes transparent to the cipher used and much more flexible. Additionally, the EVP interface will ensure the use of platform specific cryptographic acceleration such as AES-NI (the low-level interfaces do not provide the guarantee).

PKCS padding works by adding n padding bytes of value n to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size n will equal the block size. For example if the block size is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5 will be added.

When decrypting the final block is checked to see if it has the correct form.

Although the decryption operation can produce an error if padding is enabled, it is not a strong test that the input data or key is correct. A random block has better than 1 in 256 chance of being of the correct format and problems with the input data earlier on will not produce a final decrypt error.

If padding is disabled then the decryption operation will always succeed if the total amount of data decrypted is a multiple of the block size.

The functions EVP_EncryptInit(), EVP_EncryptInit_ex(), EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex(), EVP_CipherInit(), EVP_CipherInit_ex() and EVP_CipherFinal() are obsolete but are retained for compatibility with existing code. New code should use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and EVP_CipherFinal_ex() because they can reuse an existing context without allocating and freeing it up on each call.

There are some differences between functions EVP_CipherInit() and EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills the passed context object with zeros. As a consequence, EVP_CipherInit() does not allow step-by-step initialization of the ctx when the key and iv are passed in separate calls. It also means that the flags set for the CTX are removed, and it is especially important for the EVP_CIPHER_CTX_FLAG_WRAP_ALLOW flag treated specially in EVP_CipherInit_ex().

Ignoring failure returns of the EVP_CIPHER_CTX initialization functions can lead to subsequent undefined behavior when calling the functions that update or finalize the context. The only valid calls on the EVP_CIPHER_CTX when initialization fails are calls that attempt another initialization of the context or release the context.

EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.

"},{"location":"man3/EVP_EncryptInit/#bugs","title":"BUGS","text":"

EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with default key lengths. If custom ciphers exceed these values the results are unpredictable. This is because it has become standard practice to define a generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.

The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.

"},{"location":"man3/EVP_EncryptInit/#examples","title":"EXAMPLES","text":"

Encrypt a string using IDEA:

int do_crypt(char *outfile)\n{\n    unsigned char outbuf[1024];\n    int outlen, tmplen;\n    /*\n     * Bogus key and IV: we'd normally set these from\n     * another source.\n     */\n    unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};\n    unsigned char iv[] = {1,2,3,4,5,6,7,8};\n    char intext[] = \"Some Crypto Text\";\n    EVP_CIPHER_CTX *ctx;\n    FILE *out;\n\n    ctx = EVP_CIPHER_CTX_new();\n    if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n\n    if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n    /*\n     * Buffer passed to EVP_EncryptFinal() must be after data just\n     * encrypted to avoid overwriting it.\n     */\n    if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n    outlen += tmplen;\n    EVP_CIPHER_CTX_free(ctx);\n    /*\n     * Need binary mode for fopen because encrypted data is\n     * binary data. Also cannot use strlen() on it because\n     * it won't be NUL terminated and may contain embedded\n     * NULs.\n     */\n    out = fopen(outfile, \"wb\");\n    if (out == NULL) {\n        /* Error */\n        return 0;\n    }\n    fwrite(outbuf, 1, outlen, out);\n    fclose(out);\n    return 1;\n}\n

The ciphertext from the above example can be decrypted using the openssl utility with the command line (shown on two lines for clarity):

openssl idea -d \\\n    -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename\n

General encryption and decryption function example using FILE I/O and AES128 with a 128-bit key:

int do_crypt(FILE *in, FILE *out, int do_encrypt)\n{\n    /* Allow enough space in output buffer for additional block */\n    unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];\n    int inlen, outlen;\n    EVP_CIPHER_CTX *ctx;\n    /*\n     * Bogus key and IV: we'd normally set these from\n     * another source.\n     */\n    unsigned char key[] = \"0123456789abcdeF\";\n    unsigned char iv[] = \"1234567887654321\";\n\n    /* Don't set key or IV right away; we want to check lengths */\n    ctx = EVP_CIPHER_CTX_new();\n    if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,\n                            do_encrypt, NULL)) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n    OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16);\n    OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16);\n\n    /* Now we can set key and IV */\n    if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n\n    for (;;) {\n        inlen = fread(inbuf, 1, 1024, in);\n        if (inlen <= 0)\n            break;\n        if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) {\n            /* Error */\n            EVP_CIPHER_CTX_free(ctx);\n            return 0;\n        }\n        fwrite(outbuf, 1, outlen, out);\n    }\n    if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {\n        /* Error */\n        EVP_CIPHER_CTX_free(ctx);\n        return 0;\n    }\n    fwrite(outbuf, 1, outlen, out);\n\n    EVP_CIPHER_CTX_free(ctx);\n    return 1;\n}\n

Encryption using AES-CBC with a 256-bit key with \"CS1\" ciphertext stealing.

int encrypt(const unsigned char *key, const unsigned char *iv,\n            const unsigned char *msg, size_t msg_len, unsigned char *out)\n{\n   /*\n    * This assumes that key size is 32 bytes and the iv is 16 bytes.\n    * For ciphertext stealing mode the length of the ciphertext \"out\" will be\n    * the same size as the plaintext size \"msg_len\".\n    * The \"msg_len\" can be any size >= 16.\n    */\n    int ret = 0, encrypt = 1, outlen, len;\n    EVP_CIPHER_CTX *ctx = NULL;\n    EVP_CIPHER *cipher = NULL;\n    OSSL_PARAM params[2];\n\n    ctx = EVP_CIPHER_CTX_new();\n    cipher = EVP_CIPHER_fetch(NULL, \"AES-256-CBC-CTS\", NULL);\n    if (ctx == NULL || cipher == NULL)\n        goto err;\n\n    /*\n     * The default is \"CS1\" so this is not really needed,\n     * but would be needed to set either \"CS2\" or \"CS3\".\n     */\n    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE,\n                                                 \"CS1\", 0);\n    params[1] = OSSL_PARAM_construct_end();\n\n    if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params))\n        goto err;\n\n    /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */\n    if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len))\n        goto err;\n     if (!EVP_CipherFinal_ex(ctx, out + outlen, &len))\n        goto err;\n    ret = 1;\nerr:\n    EVP_CIPHER_free(cipher);\n    EVP_CIPHER_CTX_free(ctx);\n    return ret;\n}\n
"},{"location":"man3/EVP_EncryptInit/#see-also","title":"SEE ALSO","text":"

evp(7), property(7), \"ALGORITHM FETCHING\" in crypto(7), provider-cipher(7), life_cycle-cipher(7)

Supported ciphers are listed in:

EVP_aes_128_gcm(3), EVP_aria_128_gcm(3), EVP_bf_cbc(3), EVP_camellia_128_ecb(3), EVP_cast5_cbc(3), EVP_chacha20(3), EVP_des_cbc(3), EVP_desx_cbc(3), EVP_idea_cbc(3), EVP_rc2_cbc(3), EVP_rc4(3), EVP_rc5_32_12_16_cbc(3), EVP_seed_cbc(3), EVP_sm4_cbc(3),

"},{"location":"man3/EVP_EncryptInit/#history","title":"HISTORY","text":"

Support for OCB mode was added in OpenSSL 1.1.0.

EVP_CIPHER_CTX was made opaque in OpenSSL 1.1.0. As a result, EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() disappeared. EVP_CIPHER_CTX_init() remains as an alias for EVP_CIPHER_CTX_reset().

The EVP_CIPHER_CTX_cipher() function was deprecated in OpenSSL 3.0; use EVP_CIPHER_CTX_get0_cipher() instead.

The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(), EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(), EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(), EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(), EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params() functions were added in 3.0.

The EVP_CIPHER_nid(), EVP_CIPHER_name(), EVP_CIPHER_block_size(), EVP_CIPHER_key_length(), EVP_CIPHER_iv_length(), EVP_CIPHER_flags(), EVP_CIPHER_mode(), EVP_CIPHER_type(), EVP_CIPHER_CTX_nid(), EVP_CIPHER_CTX_block_size(), EVP_CIPHER_CTX_key_length(), EVP_CIPHER_CTX_iv_length(), EVP_CIPHER_CTX_tag_length(), EVP_CIPHER_CTX_num(), EVP_CIPHER_CTX_type(), and EVP_CIPHER_CTX_mode() functions were renamed to include get or get0 in their names in OpenSSL 3.0, respectively. The old names are kept as non-deprecated alias macros.

The EVP_CIPHER_CTX_encrypting() function was renamed to EVP_CIPHER_CTX_is_encrypting() in OpenSSL 3.0. The old name is kept as non-deprecated alias macro.

The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.

EVP_CIPHER_CTX_dup() was added in OpenSSL 3.2.

"},{"location":"man3/EVP_EncryptInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/EVP_KDF/","title":"EVP_KDF","text":""},{"location":"man3/EVP_KDF/#name","title":"NAME","text":"

EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup, EVP_KDF_CTX_reset, EVP_KDF_derive, EVP_KDF_CTX_get_kdf_size, EVP_KDF_get0_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a, EVP_KDF_get0_name, EVP_KDF_names_do_all, EVP_KDF_get0_description, EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided, EVP_KDF_get_params, EVP_KDF_gettable_params, EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params, EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines

"},{"location":"man3/EVP_KDF/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/kdf.h>\n\ntypedef struct evp_kdf_st EVP_KDF;\ntypedef struct evp_kdf_ctx_st EVP_KDF_CTX;\n\nEVP_KDF_CTX *EVP_KDF_CTX_new(EVP_KDF *kdf);\nconst EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);\nvoid EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);\nEVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);\nvoid EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx);\nsize_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx);\nint EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen,\n                   const OSSL_PARAM params[]);\nint EVP_KDF_up_ref(EVP_KDF *kdf);\nvoid EVP_KDF_free(EVP_KDF *kdf);\nEVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,\n                       const char *properties);\nint EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);\nconst char *EVP_KDF_get0_name(const EVP_KDF *kdf);\nconst char *EVP_KDF_get0_description(const EVP_KDF *kdf);\nconst OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);\nvoid EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx,\n                             void (*fn)(EVP_KDF *kdf, void *arg),\n                             void *arg);\nint EVP_KDF_names_do_all(const EVP_KDF *kdf,\n                         void (*fn)(const char *name, void *data),\n                         void *data);\nint EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);\nint EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);\nint EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);\nconst OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);\nconst OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);\nconst OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf);\nconst OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);\nconst OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);\n
"},{"location":"man3/EVP_KDF/#description","title":"DESCRIPTION","text":"

The EVP KDF routines are a high-level interface to Key Derivation Function algorithms and should be used instead of algorithm-specific functions.

After creating a EVP_KDF_CTX for the required algorithm using EVP_KDF_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_KDF_derive() call or using calls to EVP_KDF_CTX_set_params() before calling EVP_KDF_derive() to derive the key.

"},{"location":"man3/EVP_KDF/#types","title":"Types","text":"

EVP_KDF is a type that holds the implementation of a KDF.

EVP_KDF_CTX is a context type that holds the algorithm inputs.

"},{"location":"man3/EVP_KDF/#algorithm-implementation-fetching","title":"Algorithm implementation fetching","text":"

EVP_KDF_fetch() fetches an implementation of a KDF algorithm, given a library context libctx and a set of properties. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

See \"Key Derivation Function (KDF)\" in OSSL_PROVIDER-default(7) for the lists of algorithms supported by the default provider.

The returned value must eventually be freed with EVP_KDF_free(3).

EVP_KDF_up_ref() increments the reference count of an already fetched KDF.

EVP_KDF_free() frees a fetched algorithm. NULL is a valid parameter, for which this function is a no-op.

"},{"location":"man3/EVP_KDF/#context-manipulation-functions","title":"Context manipulation functions","text":"

EVP_KDF_CTX_new() creates a new context for the KDF implementation kdf.

EVP_KDF_CTX_free() frees up the context ctx. If ctx is NULL, nothing is done.

EVP_KDF_CTX_kdf() returns the EVP_KDF associated with the context ctx.

"},{"location":"man3/EVP_KDF/#computing-functions","title":"Computing functions","text":"

EVP_KDF_CTX_reset() resets the context to the default state as if the context had just been created.

EVP_KDF_derive() processes any parameters in Params and then derives keylen bytes of key material and places it in the key buffer. If the algorithm produces a fixed amount of output then an error will occur unless the keylen parameter is equal to that output size, as returned by EVP_KDF_CTX_get_kdf_size().

EVP_KDF_get_params() retrieves details about the implementation kdf. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_KDF_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_KDF_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.

EVP_KDF_gettable_params() returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. EVP_KDF_gettable_params() returns parameters that can be used with EVP_KDF_get_params().

EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params() return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_KDF_CTX_get_params(). EVP_KDF_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_KDF_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.

EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_KDF_CTX_set_params(). EVP_KDF_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_KDF_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

"},{"location":"man3/EVP_KDF/#information-functions","title":"Information functions","text":"

EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm produces a fixed amount of output and SIZE_MAX otherwise. If an error occurs then 0 is returned. For some algorithms an error may result if input parameters necessary to calculate a fixed output size have not yet been supplied.

EVP_KDF_is_a() returns 1 if kdf is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_KDF_get0_provider() returns the provider that holds the implementation of the given kdf.

EVP_KDF_do_all_provided() traverses all KDF implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_KDF_get0_name() return the name of the given KDF. For fetched KDFs with multiple names, only one of them is returned; it's recommended to use EVP_KDF_names_do_all() instead.

EVP_KDF_names_do_all() traverses all names for kdf, and calls fn with each name and data.

EVP_KDF_get0_description() returns a description of the kdf, meant for display and human consumption. The description is at the discretion of the kdf implementation.

"},{"location":"man3/EVP_KDF/#parameters","title":"PARAMETERS","text":"

The standard parameter names are:

"},{"location":"man3/EVP_KDF/#return-values","title":"RETURN VALUES","text":"

EVP_KDF_fetch() returns a pointer to a newly fetched EVP_KDF, or NULL if allocation failed.

EVP_KDF_get0_provider() returns a pointer to the provider for the KDF, or NULL on error.

EVP_KDF_up_ref() returns 1 on success, 0 on error.

EVP_KDF_CTX_new() returns either the newly allocated EVP_KDF_CTX structure or NULL if an error occurred.

EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value.

EVP_KDF_CTX_get_kdf_size() returns the output size. SIZE_MAX is returned to indicate that the algorithm produces a variable amount of output; 0 to indicate failure.

EVP_KDF_get0_name() returns the name of the KDF, or NULL on error.

EVP_KDF_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

The remaining functions return 1 for success and 0 or a negative value for failure. In particular, a return value of -2 indicates the operation is not supported by the KDF algorithm.

"},{"location":"man3/EVP_KDF/#notes","title":"NOTES","text":"

The KDF life-cycle is described in life_cycle-kdf(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

"},{"location":"man3/EVP_KDF/#see-also","title":"SEE ALSO","text":"

\"Key Derivation Function (KDF)\" in OSSL_PROVIDER-default(7), life_cycle-kdf(7).

"},{"location":"man3/EVP_KDF/#history","title":"HISTORY","text":"

This functionality was added in OpenSSL 3.0.

"},{"location":"man3/EVP_KDF/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man3/EVP_KEM_free/","title":"EVP_KEM_free","text":""},{"location":"man3/EVP_KEM_free/#name","title":"NAME","text":"

EVP_KEM_fetch, EVP_KEM_free, EVP_KEM_up_ref, EVP_KEM_get0_name, EVP_KEM_is_a, EVP_KEM_get0_provider, EVP_KEM_do_all_provided, EVP_KEM_names_do_all, EVP_KEM_get0_description, EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params - Functions to manage EVP_KEM algorithm objects

"},{"location":"man3/EVP_KEM_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_KEM *EVP_KEM_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                       const char *properties);\nvoid EVP_KEM_free(EVP_KEM *kem);\nint EVP_KEM_up_ref(EVP_KEM *kem);\nconst char *EVP_KEM_get0_name(const EVP_KEM *kem);\nint EVP_KEM_is_a(const EVP_KEM *kem, const char *name);\nOSSL_PROVIDER *EVP_KEM_get0_provider(const EVP_KEM *kem);\nvoid EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx,\n                             void (*fn)(EVP_KEM *kem, void *arg), void *arg);\nint EVP_KEM_names_do_all(const EVP_KEM *kem,\n                         void (*fn)(const char *name, void *data), void *data);\nconst char *EVP_KEM_get0_description(const EVP_KEM *kem);\nconst OSSL_PARAM *EVP_KEM_gettable_ctx_params(const EVP_KEM *kem);\nconst OSSL_PARAM *EVP_KEM_settable_ctx_params(const EVP_KEM *kem);\n
"},{"location":"man3/EVP_KEM_free/#description","title":"DESCRIPTION","text":"

EVP_KEM_fetch() fetches the implementation for the given algorithm from any provider offering it, within the criteria given by the properties and in the scope of the given library context ctx (see OSSL_LIB_CTX(3)). The algorithm will be one offering functions for performing asymmetric kem related tasks such as key encapsulation and decapsulation. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_KEM_free().

EVP_KEM_free() decrements the reference count for the EVP_KEM structure. Typically this structure will have been obtained from an earlier call to EVP_KEM_fetch(). If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_KEM_up_ref() increments the reference count for an EVP_KEM structure.

EVP_KEM_is_a() returns 1 if kem is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_KEM_get0_provider() returns the provider that kem was fetched from.

EVP_KEM_do_all_provided() traverses all EVP_KEMs implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_KEM_get0_name() returns the algorithm name from the provided implementation for the given kem. Note that the kem may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the kem object and should not be freed by the caller.

EVP_KEM_names_do_all() traverses all names for kem, and calls fn with each name and data.

EVP_KEM_get0_description() returns a description of the kem, meant for display and human consumption. The description is at the discretion of the kem implementation.

EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set by a key encapsulation algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_KEM_free/#return-values","title":"RETURN VALUES","text":"

EVP_KEM_fetch() returns a pointer to an EVP_KEM for success or NULL for failure.

EVP_KEM_up_ref() returns 1 for success or 0 otherwise.

EVP_KEM_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_KEM_free/#see-also","title":"SEE ALSO","text":"

\"ALGORITHM FETCHING\" in crypto(7), OSSL_PROVIDER(3)

"},{"location":"man3/EVP_KEM_free/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_KEM_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2024 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.

"},{"location":"man3/EVP_KEYEXCH_free/","title":"EVP_KEYEXCH_free","text":""},{"location":"man3/EVP_KEYEXCH_free/#name","title":"NAME","text":"

EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_get0_provider, EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided, EVP_KEYEXCH_names_do_all, EVP_KEYEXCH_get0_name, EVP_KEYEXCH_get0_description, EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params - Functions to manage EVP_KEYEXCH algorithm objects

"},{"location":"man3/EVP_KEYEXCH_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_KEYEXCH *EVP_KEYEXCH_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                               const char *properties);\nvoid EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);\nint EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);\nOSSL_PROVIDER *EVP_KEYEXCH_get0_provider(const EVP_KEYEXCH *exchange);\nint EVP_KEYEXCH_is_a(const EVP_KEYEXCH *exchange, const char *name);\nconst char *EVP_KEYEXCH_get0_name(const EVP_KEYEXCH *exchange);\nvoid EVP_KEYEXCH_do_all_provided(OSSL_LIB_CTX *libctx,\n                                 void (*fn)(EVP_KEYEXCH *exchange, void *arg),\n                                 void *arg);\nint EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange,\n                             void (*fn)(const char *name, void *data),\n                             void *data);\nconst char *EVP_KEYEXCH_get0_description(const EVP_KEYEXCH *keyexch);\nconst OSSL_PARAM *EVP_KEYEXCH_gettable_ctx_params(const EVP_KEYEXCH *keyexch);\nconst OSSL_PARAM *EVP_KEYEXCH_settable_ctx_params(const EVP_KEYEXCH *keyexch);\n
"},{"location":"man3/EVP_KEYEXCH_free/#description","title":"DESCRIPTION","text":"

EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given algorithm from any provider offering it, within the criteria given by the properties. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_KEYEXCH_free().

EVP_KEYEXCH_free() decrements the reference count for the EVP_KEYEXCH structure. Typically this structure will have been obtained from an earlier call to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_KEYEXCH_up_ref() increments the reference count for an EVP_KEYEXCH structure.

EVP_KEYEXCH_get0_provider() returns the provider that exchange was fetched from.

EVP_KEYEXCH_is_a() checks if exchange is an implementation of an algorithm that's identifiable with name.

EVP_KEYEXCH_get0_name() returns the algorithm name from the provided implementation for the given exchange. Note that the exchange may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the exchange object and should not be freed by the caller.

EVP_KEYEXCH_names_do_all() traverses all names for the exchange, and calls fn with each name and data.

EVP_KEYEXCH_get0_description() returns a description of the keyexch, meant for display and human consumption. The description is at the discretion of the keyexch implementation.

EVP_KEYEXCH_do_all_provided() traverses all key exchange implementations by all activated providers in the library context libctx, and for each of the implementations, calls fn with the implementation method and data as arguments.

EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set by a key exchange algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_KEYEXCH_free/#return-values","title":"RETURN VALUES","text":"

EVP_KEYEXCH_fetch() returns a pointer to a EVP_KEYEXCH for success or NULL for failure.

EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.

EVP_KEYEXCH_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_KEYEXCH_is_a() returns 1 of exchange was identifiable, otherwise 0.

EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_KEYEXCH_free/#see-also","title":"SEE ALSO","text":"

\"ALGORITHM FETCHING\" in crypto(7), OSSL_PROVIDER(3)

"},{"location":"man3/EVP_KEYEXCH_free/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_KEYEXCH_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man3/EVP_KEYMGMT/","title":"EVP_KEYMGMT","text":""},{"location":"man3/EVP_KEYMGMT/#name","title":"NAME","text":"

EVP_KEYMGMT, EVP_KEYMGMT_fetch, EVP_KEYMGMT_up_ref, EVP_KEYMGMT_free, EVP_KEYMGMT_get0_provider, EVP_KEYMGMT_is_a, EVP_KEYMGMT_get0_description, EVP_KEYMGMT_get0_name, EVP_KEYMGMT_do_all_provided, EVP_KEYMGMT_names_do_all, EVP_KEYMGMT_gettable_params, EVP_KEYMGMT_settable_params, EVP_KEYMGMT_gen_gettable_params, EVP_KEYMGMT_gen_settable_params - EVP key management routines

"},{"location":"man3/EVP_KEYMGMT/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef struct evp_keymgmt_st EVP_KEYMGMT;\n\nEVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                               const char *properties);\nint EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);\nvoid EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);\nconst OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt);\nint EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);\nconst char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt);\nconst char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt);\n\nvoid EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,\n                                 void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),\n                                 void *arg);\nint EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,\n                             void (*fn)(const char *name, void *data),\n                             void *data);\nconst OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt);\nconst OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt);\nconst OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt);\nconst OSSL_PARAM *EVP_KEYMGMT_gen_gettable_params(const EVP_KEYMGMT *keymgmt);\n
"},{"location":"man3/EVP_KEYMGMT/#description","title":"DESCRIPTION","text":"

EVP_KEYMGMT is a method object that represents key management implementations for different cryptographic algorithms. This method object provides functionality to have providers import key material from the outside, as well as export key material to the outside. Most of the functionality can only be used internally and has no public interface, this object is simply passed into other functions when needed.

EVP_KEYMGMT_fetch() looks for an algorithm within the provider that has been loaded into the OSSL_LIB_CTX given by ctx, having the name given by algorithm and the properties given by properties.

EVP_KEYMGMT_up_ref() increments the reference count for the given EVP_KEYMGMT keymgmt.

EVP_KEYMGMT_free() decrements the reference count for the given EVP_KEYMGMT keymgmt, and when the count reaches zero, frees it. If the argument is NULL, nothing is done.

EVP_KEYMGMT_get0_provider() returns the provider that has this particular implementation.

EVP_KEYMGMT_is_a() checks if keymgmt is an implementation of an algorithm that's identifiable with name.

EVP_KEYMGMT_get0_name() returns the algorithm name from the provided implementation for the given keymgmt. Note that the keymgmt may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the keymgmt object and should not be freed by the caller.

EVP_KEYMGMT_names_do_all() traverses all names for the keymgmt, and calls fn with each name and data.

EVP_KEYMGMT_get0_description() returns a description of the keymgmt, meant for display and human consumption. The description is at the discretion of the keymgmt implementation.

EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by all activated providers in the library context libctx, and for each of the implementations, calls fn with the implementation method and data as arguments.

EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set. EVP_KEYMGMT_gettable_params() is used by EVP_PKEY_gettable_params(3).

EVP_KEYMGMT_gen_gettable_params() and EVP_KEYMGMT_gen_settable_params() return a constant OSSL_PARAM(3) array that describes the names and types of key generation parameters that can be retrieved or set via EVP_PKEY_CTX_get_params(3) or EVP_PKEY_CTX_set_params(3) respectively.

"},{"location":"man3/EVP_KEYMGMT/#notes","title":"NOTES","text":"

EVP_KEYMGMT_fetch() may be called implicitly by other fetching functions, using the same library context and properties. Any other API that uses keys will typically do this.

"},{"location":"man3/EVP_KEYMGMT/#return-values","title":"RETURN VALUES","text":"

EVP_KEYMGMT_fetch() returns a pointer to the key management implementation represented by an EVP_KEYMGMT object, or NULL on error.

EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.

EVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_KEYMGMT_free() doesn't return any value.

EVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL on error.

EVP_KEYMGMT_is_a() returns 1 of keymgmt was identifiable, otherwise 0.

EVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error.

EVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if there isn't one.

EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params(), EVP_KEYMGMT_gen_gettable_params() and EVP_KEYMGMT_gen_settable_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_KEYMGMT/#see-also","title":"SEE ALSO","text":"

EVP_MD_fetch(3), OSSL_LIB_CTX(3)

"},{"location":"man3/EVP_KEYMGMT/#history","title":"HISTORY","text":"

The function EVP_KEYMGMT_gen_gettable_params() was added in OpenSSL 3.4.0 All other functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_KEYMGMT/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man3/EVP_MAC/","title":"EVP_MAC","text":""},{"location":"man3/EVP_MAC/#name","title":"NAME","text":"

EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free, EVP_MAC_is_a, EVP_MAC_get0_name, EVP_MAC_names_do_all, EVP_MAC_get0_description, EVP_MAC_get0_provider, EVP_MAC_get_params, EVP_MAC_gettable_params, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup, EVP_MAC_CTX_get0_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params, EVP_MAC_CTX_get_mac_size, EVP_MAC_CTX_get_block_size, EVP_Q_mac, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final, EVP_MAC_finalXOF, EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params, EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params, EVP_MAC_do_all_provided - EVP MAC routines

"},{"location":"man3/EVP_MAC/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef struct evp_mac_st EVP_MAC;\ntypedef struct evp_mac_ctx_st EVP_MAC_CTX;\n\nEVP_MAC *EVP_MAC_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,\n                       const char *properties);\nint EVP_MAC_up_ref(EVP_MAC *mac);\nvoid EVP_MAC_free(EVP_MAC *mac);\nint EVP_MAC_is_a(const EVP_MAC *mac, const char *name);\nconst char *EVP_MAC_get0_name(const EVP_MAC *mac);\nint EVP_MAC_names_do_all(const EVP_MAC *mac,\n                         void (*fn)(const char *name, void *data),\n                         void *data);\nconst char *EVP_MAC_get0_description(const EVP_MAC *mac);\nconst OSSL_PROVIDER *EVP_MAC_get0_provider(const EVP_MAC *mac);\nint EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);\n\nEVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);\nvoid EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);\nEVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);\nEVP_MAC *EVP_MAC_CTX_get0_mac(EVP_MAC_CTX *ctx);\nint EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);\nint EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);\n\nsize_t EVP_MAC_CTX_get_mac_size(EVP_MAC_CTX *ctx);\nsize_t EVP_MAC_CTX_get_block_size(EVP_MAC_CTX *ctx);\nunsigned char *EVP_Q_mac(OSSL_LIB_CTX *libctx, const char *name, const char *propq,\n                         const char *subalg, const OSSL_PARAM *params,\n                         const void *key, size_t keylen,\n                         const unsigned char *data, size_t datalen,\n                         unsigned char *out, size_t outsize, size_t *outlen);\nint EVP_MAC_init(EVP_MAC_CTX *ctx, const unsigned char *key, size_t keylen,\n                 const OSSL_PARAM params[]);\nint EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);\nint EVP_MAC_final(EVP_MAC_CTX *ctx,\n                  unsigned char *out, size_t *outl, size_t outsize);\nint EVP_MAC_finalXOF(EVP_MAC_CTX *ctx, unsigned char *out, size_t outsize);\n\nconst OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);\nconst OSSL_PARAM *EVP_MAC_gettable_ctx_params(const EVP_MAC *mac);\nconst OSSL_PARAM *EVP_MAC_settable_ctx_params(const EVP_MAC *mac);\nconst OSSL_PARAM *EVP_MAC_CTX_gettable_params(EVP_MAC_CTX *ctx);\nconst OSSL_PARAM *EVP_MAC_CTX_settable_params(EVP_MAC_CTX *ctx);\n\nvoid EVP_MAC_do_all_provided(OSSL_LIB_CTX *libctx,\n                             void (*fn)(EVP_MAC *mac, void *arg),\n                             void *arg);\n
"},{"location":"man3/EVP_MAC/#description","title":"DESCRIPTION","text":"

These types and functions help the application to calculate MACs of different types and with different underlying algorithms if there are any.

MACs are a bit complex insofar that some of them use other algorithms for actual computation. HMAC uses a digest, and CMAC uses a cipher. Therefore, there are sometimes two contexts to keep track of, one for the MAC algorithm itself and one for the underlying computation algorithm if there is one.

To make things less ambiguous, this manual talks about a \"context\" or \"MAC context\", which is to denote the MAC level context, and about a \"underlying context\", or \"computation context\", which is to denote the context for the underlying computation algorithm if there is one.

"},{"location":"man3/EVP_MAC/#types","title":"Types","text":"

EVP_MAC is a type that holds the implementation of a MAC.

EVP_MAC_CTX is a context type that holds internal MAC information as well as a reference to a computation context, for those MACs that rely on an underlying computation algorithm.

"},{"location":"man3/EVP_MAC/#algorithm-implementation-fetching","title":"Algorithm implementation fetching","text":"

EVP_MAC_fetch() fetches an implementation of a MAC algorithm, given a library context libctx and a set of properties. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

See \"Message Authentication Code (MAC)\" in OSSL_PROVIDER-default(7) for the list of algorithms supported by the default provider.

The returned value must eventually be freed with EVP_MAC_free(3).

EVP_MAC_up_ref() increments the reference count of an already fetched MAC.

EVP_MAC_free() frees a fetched algorithm. NULL is a valid parameter, for which this function is a no-op.

"},{"location":"man3/EVP_MAC/#context-manipulation-functions","title":"Context manipulation functions","text":"

EVP_MAC_CTX_new() creates a new context for the MAC type mac. The created context can then be used with most other functions described here.

EVP_MAC_CTX_free() frees the contents of the context, including an underlying context if there is one, as well as the context itself. NULL is a valid parameter, for which this function is a no-op.

EVP_MAC_CTX_dup() duplicates the src context and returns a newly allocated context.

EVP_MAC_CTX_get0_mac() returns the EVP_MAC associated with the context ctx.

"},{"location":"man3/EVP_MAC/#computing-functions","title":"Computing functions","text":"

EVP_Q_mac() computes the message authentication code of data with length datalen using the MAC algorithm name and the key key with length keylen. The MAC algorithm is fetched using any given libctx and property query string propq. It takes parameters subalg and further params, both of which may be NULL if not needed. If out is not NULL, it places the result in the memory pointed at by out, but only if outsize is sufficient (otherwise no computation is made). If out is NULL, it allocates and uses a buffer of suitable length, which will be returned on success and must be freed by the caller. In either case, also on error, it assigns the number of bytes written to *outlen unless outlen is NULL.

EVP_MAC_init() sets up the underlying context ctx with information given via the key and params arguments. The MAC key has a length of keylen and the parameters in params are processed before setting the key. If key is NULL, the key must be set via params either as part of this call or separately using EVP_MAC_CTX_set_params(). Providing non-NULL params to this function is equivalent to calling EVP_MAC_CTX_set_params() with those params for the same ctx beforehand. Note: There are additional requirements for some MAC algorithms during re-initalization (i.e. calling EVP_MAC_init() on an EVP_MAC after EVP_MAC_final() has been called on the same object). See the NOTES section below.

EVP_MAC_init() should be called before EVP_MAC_update() and EVP_MAC_final().

EVP_MAC_update() adds datalen bytes from data to the MAC input.

EVP_MAC_final() does the final computation and stores the result in the memory pointed at by out of size outsize, and sets the number of bytes written in *outl at. If out is NULL or outsize is too small, then no computation is made. To figure out what the output length will be and allocate space for it dynamically, simply call with out being NULL and outl pointing at a valid location, then allocate space and make a second call with out pointing at the allocated space.

EVP_MAC_finalXOF() does the final computation for an XOF based MAC and stores the result in the memory pointed at by out of size outsize.

EVP_MAC_get_params() retrieves details about the implementation mac. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_MAC_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_MAC_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. If params are NULL, the underlying context should do nothing and return 1. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.

EVP_MAC_gettable_params() returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. EVP_MAC_gettable_params() returns parameters that can be used with EVP_MAC_get_params().

EVP_MAC_gettable_ctx_params() and EVP_MAC_CTX_gettable_params() return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_MAC_CTX_get_params(). EVP_MAC_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_MAC_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.

EVP_MAC_settable_ctx_params() and EVP_MAC_CTX_settable_params() return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_MAC_CTX_set_params(). EVP_MAC_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_MAC_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

"},{"location":"man3/EVP_MAC/#information-functions","title":"Information functions","text":"

EVP_MAC_CTX_get_mac_size() returns the MAC output size for the given context.

EVP_MAC_CTX_get_block_size() returns the MAC block size for the given context. Not all MAC algorithms support this.

EVP_MAC_is_a() checks if the given mac is an implementation of an algorithm that's identifiable with name.

EVP_MAC_get0_provider() returns the provider that holds the implementation of the given mac.

EVP_MAC_do_all_provided() traverses all MAC implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_MAC_get0_name() return the name of the given MAC. For fetched MACs with multiple names, only one of them is returned; it's recommended to use EVP_MAC_names_do_all() instead.

EVP_MAC_names_do_all() traverses all names for mac, and calls fn with each name and data.

EVP_MAC_get0_description() returns a description of the mac, meant for display and human consumption. The description is at the discretion of the mac implementation.

"},{"location":"man3/EVP_MAC/#parameters","title":"PARAMETERS","text":"

Parameters are identified by name as strings, and have an expected data type and maximum size. OpenSSL has a set of macros for parameter names it expects to see in its own MAC implementations. Here, we show all three, the OpenSSL macro for the parameter name, the name in string form, and a type description.

The standard parameter names are:

All these parameters should be used before the calls to any of EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full computation. Anything else may give undefined results.

"},{"location":"man3/EVP_MAC/#notes","title":"NOTES","text":"

The MAC life-cycle is described in life_cycle-mac(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

The usage of the parameter names \"custom\", \"iv\" and \"salt\" correspond to the names used in the standard where the algorithm was defined.

Some MAC algorithms store internal state that cannot be extracted during re-initalization. For example GMAC cannot extract an IV from the underlying CIPHER context, and so calling EVP_MAC_init() on an EVP_MAC object after EVP_MAC_final() has been called cannot reset its cipher state to what it was when the IV was initially generated. For such instances, an OSSL_MAC_PARAM_IV parameter must be passed with each call to EVP_MAC_init().

"},{"location":"man3/EVP_MAC/#return-values","title":"RETURN VALUES","text":"

EVP_MAC_fetch() returns a pointer to a newly fetched EVP_MAC, or NULL if allocation failed.

EVP_MAC_up_ref() returns 1 on success, 0 on error.

EVP_MAC_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_MAC_free() returns nothing at all.

EVP_MAC_is_a() returns 1 if the given method can be identified with the given name, otherwise 0.

EVP_MAC_get0_name() returns a name of the MAC, or NULL on error.

EVP_MAC_get0_provider() returns a pointer to the provider for the MAC, or NULL on error.

EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly created EVP_MAC_CTX, or NULL if allocation failed.

EVP_MAC_CTX_free() returns nothing at all.

EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on success, 0 on error.

EVP_Q_mac() returns a pointer to the computed MAC value, or NULL on error.

EVP_MAC_init(), EVP_MAC_update(), EVP_MAC_final(), and EVP_MAC_finalXOF() return 1 on success, 0 on error.

EVP_MAC_CTX_get_mac_size() returns the expected output size, or 0 if it isn't set. If it isn't set, a call to EVP_MAC_init() will set it.

EVP_MAC_CTX_get_block_size() returns the block size, or 0 if it isn't set. If it isn't set, a call to EVP_MAC_init() will set it.

EVP_MAC_do_all_provided() returns nothing at all.

"},{"location":"man3/EVP_MAC/#examples","title":"EXAMPLES","text":"
#include <stdlib.h>\n#include <stdio.h>\n#include <string.h>\n#include <stdarg.h>\n#include <unistd.h>\n\n#include <openssl/evp.h>\n#include <openssl/err.h>\n#include <openssl/params.h>\n\nint main() {\n    EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv(\"MY_MAC\"), NULL);\n    const char *cipher = getenv(\"MY_MAC_CIPHER\");\n    const char *digest = getenv(\"MY_MAC_DIGEST\");\n    const char *key = getenv(\"MY_KEY\");\n    EVP_MAC_CTX *ctx = NULL;\n\n    unsigned char buf[4096];\n    size_t read_l;\n    size_t final_l;\n\n    size_t i;\n\n    OSSL_PARAM params[3];\n    size_t params_n = 0;\n\n    if (cipher != NULL)\n        params[params_n++] =\n            OSSL_PARAM_construct_utf8_string(\"cipher\", (char*)cipher, 0);\n    if (digest != NULL)\n        params[params_n++] =\n            OSSL_PARAM_construct_utf8_string(\"digest\", (char*)digest, 0);\n    params[params_n] = OSSL_PARAM_construct_end();\n\n    if (mac == NULL\n        || key == NULL\n        || (ctx = EVP_MAC_CTX_new(mac)) == NULL\n        || !EVP_MAC_init(ctx, (const unsigned char *)key, strlen(key),\n                         params))\n        goto err;\n\n    while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {\n        if (!EVP_MAC_update(ctx, buf, read_l))\n            goto err;\n    }\n\n    if (!EVP_MAC_final(ctx, buf, &final_l, sizeof(buf)))\n        goto err;\n\n    printf(\"Result: \");\n    for (i = 0; i < final_l; i++)\n        printf(\"%02X\", buf[i]);\n    printf(\"\\n\");\n\n    EVP_MAC_CTX_free(ctx);\n    EVP_MAC_free(mac);\n    exit(0);\n\n err:\n    EVP_MAC_CTX_free(ctx);\n    EVP_MAC_free(mac);\n    fprintf(stderr, \"Something went wrong\\n\");\n    ERR_print_errors_fp(stderr);\n    exit (1);\n}\n

A run of this program, called with correct environment variables, can look like this:

$ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \\\n  LD_LIBRARY_PATH=. ./foo < foo.c\nResult: C5C06683CD9DDEF904D754505C560A4E\n

(in this example, that program was stored in foo.c and compiled to ./foo)

"},{"location":"man3/EVP_MAC/#see-also","title":"SEE ALSO","text":"

property(7) OSSL_PARAM(3), EVP_MAC-BLAKE2(7), EVP_MAC-CMAC(7), EVP_MAC-GMAC(7), EVP_MAC-HMAC(7), EVP_MAC-KMAC(7), EVP_MAC-Siphash(7), EVP_MAC-Poly1305(7), provider-mac(7), life_cycle-mac(7)

"},{"location":"man3/EVP_MAC/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_MAC/#copyright","title":"COPYRIGHT","text":"

Copyright 2018-2024 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.

"},{"location":"man3/EVP_MD_meth_new/","title":"EVP_MD_meth_new","text":""},{"location":"man3/EVP_MD_meth_new/#name","title":"NAME","text":"

EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize, EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize, EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update, EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup, EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize, EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize, EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update, EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup, EVP_MD_meth_get_ctrl - Routines to build up legacy EVP_MD methods

"},{"location":"man3/EVP_MD_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);\nvoid EVP_MD_meth_free(EVP_MD *md);\nEVP_MD *EVP_MD_meth_dup(const EVP_MD *md);\n\nint EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);\nint EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);\nint EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);\nint EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);\nint EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx));\nint EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx,\n                                                     const void *data,\n                                                     size_t count));\nint EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx,\n                                                   unsigned char *md));\nint EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,\n                                                 const EVP_MD_CTX *from));\nint EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));\nint EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,\n                                                 int p1, void *p2));\n\nint EVP_MD_meth_get_input_blocksize(const EVP_MD *md);\nint EVP_MD_meth_get_result_size(const EVP_MD *md);\nint EVP_MD_meth_get_app_datasize(const EVP_MD *md);\nunsigned long EVP_MD_meth_get_flags(const EVP_MD *md);\nint (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx);\nint (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx,\n                                                const void *data,\n                                                size_t count);\nint (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx,\n                                               unsigned char *md);\nint (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to,\n                                              const EVP_MD_CTX *from);\nint (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx);\nint (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,\n                                              int p1, void *p2);\n
"},{"location":"man3/EVP_MD_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the OSSL_PROVIDER APIs.

The EVP_MD type is a structure for digest method implementation. It can also have associated public/private key signing and verifying routines.

EVP_MD_meth_new() creates a new EVP_MD structure. These EVP_MD structures are reference counted.

EVP_MD_meth_dup() creates a copy of md.

EVP_MD_meth_free() decrements the reference count for the EVP_MD structure. If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_MD_meth_set_input_blocksize() sets the internal input block size for the method md to blocksize bytes.

EVP_MD_meth_set_result_size() sets the size of the result that the digest method in md is expected to produce to resultsize bytes.

The digest method may have its own private data, which OpenSSL will allocate for it. EVP_MD_meth_set_app_datasize() should be used to set the size for it to datasize.

EVP_MD_meth_set_flags() sets the flags to describe optional behaviours in the particular md. Several flags can be or'd together. The available flags are:

EVP_MD_meth_set_init() sets the digest init function for md. The digest init function is called by EVP_Digest(), EVP_DigestInit(), EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit() and EVP_VerifyInit_ex().

EVP_MD_meth_set_update() sets the digest update function for md. The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and EVP_SignUpdate().

EVP_MD_meth_set_final() sets the digest final function for md. The digest final function is called by EVP_Digest(), EVP_DigestFinal(), EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().

EVP_MD_meth_set_copy() sets the function for md to do extra computations after the method's private data structure has been copied from one EVP_MD_CTX to another. If all that's needed is to copy the data, there is no need for this copy function. Note that the copy function is passed two EVP_MD_CTX *, the private data structure is then available with EVP_MD_CTX_get0_md_data(). This copy function is called by EVP_MD_CTX_copy() and EVP_MD_CTX_copy_ex().

EVP_MD_meth_set_cleanup() sets the function for md to do extra cleanup before the method's private data structure is cleaned out and freed. Note that the cleanup function is passed a EVP_MD_CTX *, the private data structure is then available with EVP_MD_CTX_get0_md_data(). This cleanup function is called by EVP_MD_CTX_reset() and EVP_MD_CTX_free().

EVP_MD_meth_set_ctrl() sets the control function for md. See EVP_MD_CTX_ctrl(3) for the available controls.

EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(), EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(), EVP_MD_meth_get_init(), EVP_MD_meth_get_update(), EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(), EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used to retrieve the method data given with the EVP_MD_meth_set_*() functions above.

"},{"location":"man3/EVP_MD_meth_new/#return-values","title":"RETURN VALUES","text":"

EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly created EVP_MD, or NULL on failure. All EVP_MD_meth_set_*() functions return 1. EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(), EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the indicated sizes or flags. All other EVP_CIPHER_meth_get_*() functions return pointers to their respective md function.

"},{"location":"man3/EVP_MD_meth_new/#see-also","title":"SEE ALSO","text":"

EVP_DigestInit(3), EVP_SignInit(3), EVP_VerifyInit(3)

"},{"location":"man3/EVP_MD_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The EVP_MD structure was openly available in OpenSSL before version 1.1. The functions described here were added in OpenSSL 1.1. The EVP_MD structure created with these functions became reference counted in OpenSSL 3.0.

"},{"location":"man3/EVP_MD_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/EVP_OpenInit/","title":"EVP_OpenInit","text":""},{"location":"man3/EVP_OpenInit/#name","title":"NAME","text":"

EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption

"},{"location":"man3/EVP_OpenInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek,\n                 int ekl, unsigned char *iv, EVP_PKEY *priv);\nint EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,\n                   int *outl, unsigned char *in, int inl);\nint EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);\n
"},{"location":"man3/EVP_OpenInit/#description","title":"DESCRIPTION","text":"

The EVP envelope routines are a high-level interface to envelope decryption. They decrypt a public key encrypted symmetric key and then decrypt data using it.

EVP_OpenInit() initializes a cipher context ctx for decryption with cipher type. It decrypts the encrypted symmetric key of length ekl bytes passed in the ek parameter using the private key priv. The IV is supplied in the iv parameter.

EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as documented on the EVP_EncryptInit(3) manual page.

"},{"location":"man3/EVP_OpenInit/#notes","title":"NOTES","text":"

It is possible to call EVP_OpenInit() twice in the same way as EVP_DecryptInit(). The first call should have priv set to NULL and (after setting any cipher parameters) it should be called again with type set to NULL.

If the cipher passed in the type parameter is a variable length cipher then the key length will be set to the value of the recovered key length. If the cipher is a fixed length cipher then the recovered key length must match the fixed cipher length.

"},{"location":"man3/EVP_OpenInit/#return-values","title":"RETURN VALUES","text":"

EVP_OpenInit() returns 0 on error or a non zero integer (actually the recovered secret key size) if successful.

EVP_OpenUpdate() returns 1 for success or 0 for failure.

EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.

"},{"location":"man3/EVP_OpenInit/#see-also","title":"SEE ALSO","text":"

evp(7), RAND_bytes(3), EVP_EncryptInit(3), EVP_SealInit(3)

"},{"location":"man3/EVP_OpenInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PBE_CipherInit/","title":"EVP_PBE_CipherInit","text":""},{"location":"man3/EVP_PBE_CipherInit/#name","title":"NAME","text":"

EVP_PBE_CipherInit, EVP_PBE_CipherInit_ex, EVP_PBE_find, EVP_PBE_find_ex, EVP_PBE_alg_add_type, EVP_PBE_alg_add - Password based encryption routines

"},{"location":"man3/EVP_PBE_CipherInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PBE_CipherInit(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,\n                       ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de);\nint EVP_PBE_CipherInit_ex(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,\n                          ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de,\n                          OSSL_LIB_CTX *libctx, const char *propq);\n\nint EVP_PBE_find(int type, int pbe_nid, int *pcnid, int *pmnid,\n                 EVP_PBE_KEYGEN **pkeygen);\nint EVP_PBE_find_ex(int type, int pbe_nid, int *pcnid, int *pmnid,\n                    EVP_PBE_KEYGEN **pkeygen, EVP_PBE_KEYGEN_EX **keygen_ex);\n\nint EVP_PBE_alg_add_type(int pbe_type, int pbe_nid, int cipher_nid,\n                         int md_nid, EVP_PBE_KEYGEN *keygen);\nint EVP_PBE_alg_add(int nid, const EVP_CIPHER *cipher, const EVP_MD *md,\n                    EVP_PBE_KEYGEN *keygen);\n
"},{"location":"man3/EVP_PBE_CipherInit/#description","title":"DESCRIPTION","text":""},{"location":"man3/EVP_PBE_CipherInit/#pbe-operations","title":"PBE operations","text":"

EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() initialise an EVP_CIPHER_CTX ctx for encryption (en_de=1) or decryption (en_de=0) using the password pass of length passlen. The PBE algorithm type and parameters are extracted from an OID pbe_obj and parameters param.

EVP_PBE_CipherInit_ex() also allows the application to specify a library context libctx and property query propq to select appropriate algorithm implementations.

"},{"location":"man3/EVP_PBE_CipherInit/#pbe-algorithm-search","title":"PBE algorithm search","text":"

EVP_PBE_find() and EVP_PBE_find_ex() search for a matching algorithm using two parameters:

1. An algorithm type type which can be:

2. A pbe_nid which can represent the algorithm identifier with parameters e.g. NID_pbeWithSHA1AndRC2_CBC or an algorithm class e.g. NID_pbes2.

They return the algorithm's cipher ID pcnid, digest ID pmnid and a key generation function for the algorithm pkeygen. EVP_PBE_CipherInit_ex() also returns an extended key generation function keygen_ex which takes a library context and property query.

If a NULL is supplied for any of pcnid, pmnid, pkeygen or pkeygen_ex then this parameter is not returned.

"},{"location":"man3/EVP_PBE_CipherInit/#pbe-algorithm-add","title":"PBE algorithm add","text":"

EVP_PBE_alg_add_type() and EVP_PBE_alg_add() add an algorithm to the list of known algorithms. Their parameters have the same meaning as for EVP_PBE_find() and EVP_PBE_find_ex() functions.

"},{"location":"man3/EVP_PBE_CipherInit/#notes","title":"NOTES","text":"

The arguments pbe_obj and param to EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() together form an X509_ALGOR and can often be extracted directly from this structure.

"},{"location":"man3/EVP_PBE_CipherInit/#return-values","title":"RETURN VALUES","text":"

Return value is 1 for success and 0 if an error occurred.

"},{"location":"man3/EVP_PBE_CipherInit/#see-also","title":"SEE ALSO","text":"

PKCS5_PBE_keyivgen(3), PKCS12_PBE_keyivgen_ex(3), PKCS5_v2_PBE_keyivgen_ex(3), PKCS12_pbe_crypt_ex(3), PKCS12_create_ex(3)

"},{"location":"man3/EVP_PBE_CipherInit/#history","title":"HISTORY","text":"

EVP_PBE_CipherInit_ex() and EVP_PBE_find_ex() were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PBE_CipherInit/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_PKEY2PKCS8/","title":"EVP_PKEY2PKCS8","text":""},{"location":"man3/EVP_PKEY2PKCS8/#name","title":"NAME","text":"

EVP_PKEY2PKCS8, EVP_PKCS82PKEY_ex, EVP_PKCS82PKEY - Convert a private key to/from PKCS8

"},{"location":"man3/EVP_PKEY2PKCS8/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nPKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey);\nEVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8);\nEVP_PKEY *EVP_PKCS82PKEY_ex(const PKCS8_PRIV_KEY_INFO *p8, OSSL_LIB_CTX *libctx,\n                            const char *propq);\n
"},{"location":"man3/EVP_PKEY2PKCS8/#description","title":"DESCRIPTION","text":"

EVP_PKEY2PKCS8() converts a private key pkey into a returned PKCS8 object.

EVP_PKCS82PKEY_ex() converts a PKCS8 object p8 into a returned private key. It uses libctx and propq when fetching algorithms.

EVP_PKCS82PKEY() is similar to EVP_PKCS82PKEY_ex() but uses default values of NULL for the libctx and propq.

"},{"location":"man3/EVP_PKEY2PKCS8/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY2PKCS8() returns a PKCS8 object on success. EVP_PKCS82PKEY() and EVP_PKCS82PKEY_ex() return a private key on success.

All functions return NULL if the operation fails.

"},{"location":"man3/EVP_PKEY2PKCS8/#see-also","title":"SEE ALSO","text":"

PKCS8_pkey_add1_attr(3),

"},{"location":"man3/EVP_PKEY2PKCS8/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2022 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.

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/","title":"EVP_PKEY_ASN1_METHOD","text":""},{"location":"man3/EVP_PKEY_ASN1_METHOD/#name","title":"NAME","text":"

EVP_PKEY_ASN1_METHOD, EVP_PKEY_asn1_new, EVP_PKEY_asn1_copy, EVP_PKEY_asn1_free, EVP_PKEY_asn1_add0, EVP_PKEY_asn1_add_alias, EVP_PKEY_asn1_set_public, EVP_PKEY_asn1_set_private, EVP_PKEY_asn1_set_param, EVP_PKEY_asn1_set_free, EVP_PKEY_asn1_set_ctrl, EVP_PKEY_asn1_set_item, EVP_PKEY_asn1_set_siginf, EVP_PKEY_asn1_set_check, EVP_PKEY_asn1_set_public_check, EVP_PKEY_asn1_set_param_check, EVP_PKEY_asn1_set_security_bits, EVP_PKEY_asn1_set_set_priv_key, EVP_PKEY_asn1_set_set_pub_key, EVP_PKEY_asn1_set_get_priv_key, EVP_PKEY_asn1_set_get_pub_key, EVP_PKEY_get0_asn1 - manipulating and registering EVP_PKEY_ASN1_METHOD structure

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;\n\nEVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,\n                                        const char *pem_str,\n                                        const char *info);\nvoid EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,\n                        const EVP_PKEY_ASN1_METHOD *src);\nvoid EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);\nint EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);\nint EVP_PKEY_asn1_add_alias(int to, int from);\n\nvoid EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,\n                              int (*pub_decode) (EVP_PKEY *pk,\n                                                 const X509_PUBKEY *pub),\n                              int (*pub_encode) (X509_PUBKEY *pub,\n                                                 const EVP_PKEY *pk),\n                              int (*pub_cmp) (const EVP_PKEY *a,\n                                              const EVP_PKEY *b),\n                              int (*pub_print) (BIO *out,\n                                                const EVP_PKEY *pkey,\n                                                int indent, ASN1_PCTX *pctx),\n                              int (*pkey_size) (const EVP_PKEY *pk),\n                              int (*pkey_bits) (const EVP_PKEY *pk));\nvoid EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,\n                               int (*priv_decode) (EVP_PKEY *pk,\n                                                   const PKCS8_PRIV_KEY_INFO\n                                                   *p8inf),\n                               int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,\n                                                   const EVP_PKEY *pk),\n                               int (*priv_print) (BIO *out,\n                                                  const EVP_PKEY *pkey,\n                                                  int indent,\n                                                  ASN1_PCTX *pctx));\nvoid EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,\n                             int (*param_decode) (EVP_PKEY *pkey,\n                                                  const unsigned char **pder,\n                                                  int derlen),\n                             int (*param_encode) (const EVP_PKEY *pkey,\n                                                  unsigned char **pder),\n                             int (*param_missing) (const EVP_PKEY *pk),\n                             int (*param_copy) (EVP_PKEY *to,\n                                                const EVP_PKEY *from),\n                             int (*param_cmp) (const EVP_PKEY *a,\n                                               const EVP_PKEY *b),\n                             int (*param_print) (BIO *out,\n                                                 const EVP_PKEY *pkey,\n                                                 int indent,\n                                                 ASN1_PCTX *pctx));\n\nvoid EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,\n                            void (*pkey_free) (EVP_PKEY *pkey));\nvoid EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,\n                            int (*pkey_ctrl) (EVP_PKEY *pkey, int op,\n                                              long arg1, void *arg2));\nvoid EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,\n                            int (*item_verify) (EVP_MD_CTX *ctx,\n                                                const ASN1_ITEM *it,\n                                                void *asn,\n                                                X509_ALGOR *a,\n                                                ASN1_BIT_STRING *sig,\n                                                EVP_PKEY *pkey),\n                            int (*item_sign) (EVP_MD_CTX *ctx,\n                                              const ASN1_ITEM *it,\n                                              void *asn,\n                                              X509_ALGOR *alg1,\n                                              X509_ALGOR *alg2,\n                                              ASN1_BIT_STRING *sig));\n\nvoid EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,\n                              int (*siginf_set) (X509_SIG_INFO *siginf,\n                                                 const X509_ALGOR *alg,\n                                                 const ASN1_STRING *sig));\n\nvoid EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,\n                             int (*pkey_check) (const EVP_PKEY *pk));\n\nvoid EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,\n                                    int (*pkey_pub_check) (const EVP_PKEY *pk));\n\nvoid EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,\n                                   int (*pkey_param_check) (const EVP_PKEY *pk));\n\nvoid EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,\n                                     int (*pkey_security_bits) (const EVP_PKEY\n                                                                *pk));\n\nvoid EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,\n                                    int (*set_priv_key) (EVP_PKEY *pk,\n                                                         const unsigned char\n                                                            *priv,\n                                                         size_t len));\n\nvoid EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth,\n                                   int (*set_pub_key) (EVP_PKEY *pk,\n                                                       const unsigned char *pub,\n                                                       size_t len));\n\nvoid EVP_PKEY_asn1_set_get_priv_key(EVP_PKEY_ASN1_METHOD *ameth,\n                                    int (*get_priv_key) (const EVP_PKEY *pk,\n                                                         unsigned char *priv,\n                                                         size_t *len));\n\nvoid EVP_PKEY_asn1_set_get_pub_key(EVP_PKEY_ASN1_METHOD *ameth,\n                                   int (*get_pub_key) (const EVP_PKEY *pk,\n                                                       unsigned char *pub,\n                                                       size_t *len));\n\nconst EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);\n
"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#description","title":"DESCRIPTION","text":"

EVP_PKEY_ASN1_METHOD is a structure which holds a set of ASN.1 conversion, printing and information methods for a specific public key algorithm.

There are two places where the EVP_PKEY_ASN1_METHOD objects are stored: one is a built-in array representing the standard methods for different algorithms, and the other one is a stack of user-defined application-specific methods, which can be manipulated by using EVP_PKEY_asn1_add0(3).

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#methods","title":"Methods","text":"

The methods are the underlying implementations of a particular public key algorithm present by the EVP_PKEY object.

int (*pub_decode) (EVP_PKEY *pk, const X509_PUBKEY *pub);\nint (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk);\nint (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);\nint (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent,\n                  ASN1_PCTX *pctx);\n

The pub_decode() and pub_encode() methods are called to decode / encode X509_PUBKEY ASN.1 parameters to / from pk. They MUST return 0 on error, 1 on success. They're called by X509_PUBKEY_get0(3) and X509_PUBKEY_set(3).

The pub_cmp() method is called when two public keys are to be compared. It MUST return 1 when the keys are equal, 0 otherwise. It's called by EVP_PKEY_eq(3).

The pub_print() method is called to print a public key in humanly readable text to out, indented indent spaces. It MUST return 0 on error, 1 on success. It's called by EVP_PKEY_print_public(3).

int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf);\nint (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk);\nint (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent,\n                   ASN1_PCTX *pctx);\n

The priv_decode() and priv_encode() methods are called to decode / encode PKCS8_PRIV_KEY_INFO form private key to / from pk. They MUST return 0 on error, 1 on success. They're called by EVP_PKCS82PKEY(3) and EVP_PKEY2PKCS8(3).

The priv_print() method is called to print a private key in humanly readable text to out, indented indent spaces. It MUST return 0 on error, 1 on success. It's called by EVP_PKEY_print_private(3).

int (*pkey_size) (const EVP_PKEY *pk);\nint (*pkey_bits) (const EVP_PKEY *pk);\nint (*pkey_security_bits) (const EVP_PKEY *pk);\n

The pkey_size() method returns the key size in bytes. It's called by EVP_PKEY_get_size(3).

The pkey_bits() method returns the key size in bits. It's called by EVP_PKEY_get_bits(3).

int (*param_decode) (EVP_PKEY *pkey,\n                     const unsigned char **pder, int derlen);\nint (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder);\nint (*param_missing) (const EVP_PKEY *pk);\nint (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from);\nint (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);\nint (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent,\n                    ASN1_PCTX *pctx);\n

The param_decode() and param_encode() methods are called to decode / encode DER formatted parameters to / from pk. They MUST return 0 on error, 1 on success. They're called by PEM_read_bio_Parameters(3) and the file: OSSL_STORE_LOADER(3).

The param_missing() method returns 0 if a key parameter is missing, otherwise 1. It's called by EVP_PKEY_missing_parameters(3).

The param_copy() method copies key parameters from from to to. It MUST return 0 on error, 1 on success. It's called by EVP_PKEY_copy_parameters(3).

The param_cmp() method compares the parameters of keys a and b. It MUST return 1 when the keys are equal, 0 when not equal, or a negative number on error. It's called by EVP_PKEY_parameters_eq(3).

The param_print() method prints the private key parameters in humanly readable text to out, indented indent spaces. It MUST return 0 on error, 1 on success. It's called by EVP_PKEY_print_params(3).

int (*sig_print) (BIO *out,\n                  const X509_ALGOR *sigalg, const ASN1_STRING *sig,\n                  int indent, ASN1_PCTX *pctx);\n

The sig_print() method prints a signature in humanly readable text to out, indented indent spaces. sigalg contains the exact signature algorithm. If the signature in sig doesn't correspond to what this method expects, X509_signature_dump() must be used as a last resort. It MUST return 0 on error, 1 on success. It's called by X509_signature_print(3).

void (*pkey_free) (EVP_PKEY *pkey);\n

The pkey_free() method helps freeing the internals of pkey. It's called by EVP_PKEY_free(3), EVP_PKEY_set_type(3), EVP_PKEY_set_type_str(3), and EVP_PKEY_assign(3).

int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);\n

The pkey_ctrl() method adds extra algorithm specific control. It's called by EVP_PKEY_get_default_digest_nid(3), EVP_PKEY_set1_encoded_public_key(3), EVP_PKEY_get1_encoded_public_key(3), PKCS7_SIGNER_INFO_set(3), PKCS7_RECIP_INFO_set(3), ...

int (*old_priv_decode) (EVP_PKEY *pkey,\n                        const unsigned char **pder, int derlen);\nint (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);\n

The old_priv_decode() and old_priv_encode() methods decode / encode they private key pkey from / to a DER formatted array. These are exclusively used to help decoding / encoding older (pre PKCS#8) PEM formatted encrypted private keys. old_priv_decode() MUST return 0 on error, 1 on success. old_priv_encode() MUST the return same kind of values as i2d_PrivateKey(). They're called by d2i_PrivateKey(3) and i2d_PrivateKey(3).

int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,\n                    X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);\nint (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,\n                  X509_ALGOR *alg1, X509_ALGOR *alg2,\n                  ASN1_BIT_STRING *sig);\n

The item_sign() and item_verify() methods make it possible to have algorithm specific signatures and verification of them.

item_sign() MUST return one of:

item_verify() MUST return one of:

item_verify() and item_sign() are called by ASN1_item_verify(3) and ASN1_item_sign(3), and by extension, X509_verify(3), X509_REQ_verify(3), X509_sign(3), X509_REQ_sign(3), ...

int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,\n                   const ASN1_STRING *sig);\n

The siginf_set() method is used to set custom X509_SIG_INFO parameters. It MUST return 0 on error, or 1 on success. It's called as part of X509_check_purpose(3), X509_check_ca(3) and X509_check_issued(3).

int (*pkey_check) (const EVP_PKEY *pk);\nint (*pkey_public_check) (const EVP_PKEY *pk);\nint (*pkey_param_check) (const EVP_PKEY *pk);\n

The pkey_check(), pkey_public_check() and pkey_param_check() methods are used to check the validity of pk for key-pair, public component and parameters, respectively. They MUST return 0 for an invalid key, or 1 for a valid key. They are called by EVP_PKEY_check(3), EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) respectively.

int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);\nint (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);\n

The set_priv_key() and set_pub_key() methods are used to set the raw private and public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success. They are called by EVP_PKEY_new_raw_private_key(3), and EVP_PKEY_new_raw_public_key(3) respectively.

size_t (*dirty) (const EVP_PKEY *pk);\nvoid *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);\n

dirty_cnt() returns the internal key's dirty count. This can be used to synchronise different copies of the same keys.

The export_to() method exports the key material from the given key to a provider, through the EVP_KEYMGMT(3) interface, if that provider supports importing key material.

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#functions","title":"Functions","text":"

EVP_PKEY_asn1_new() creates and returns a new EVP_PKEY_ASN1_METHOD object, and associates the given id, flags, pem_str and info. id is a NID, pem_str is the PEM type string, info is a descriptive string. The following flags are supported:

ASN1_PKEY_SIGPARAM_NULL\n

If ASN1_PKEY_SIGPARAM_NULL is set, then the signature algorithm parameters are given the type V_ASN1_NULL by default, otherwise they will be given the type V_ASN1_UNDEF (i.e. the parameter is omitted). See X509_ALGOR_set0(3) for more information.

EVP_PKEY_asn1_copy() copies an EVP_PKEY_ASN1_METHOD object from src to dst. This function is not thread safe, it's recommended to only use this when initializing the application.

EVP_PKEY_asn1_free() frees an existing EVP_PKEY_ASN1_METHOD pointed by ameth. If the argument is NULL, nothing is done.

EVP_PKEY_asn1_add0() adds ameth to the user defined stack of methods unless another EVP_PKEY_ASN1_METHOD with the same NID is already there. This function is not thread safe, it's recommended to only use this when initializing the application.

EVP_PKEY_asn1_add_alias() creates an alias with the NID to for the EVP_PKEY_ASN1_METHOD with NID from unless another EVP_PKEY_ASN1_METHOD with the same NID is already added. This function is not thread safe, it's recommended to only use this when initializing the application.

EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(), EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(), EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(), EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(), EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(), EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(), EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given EVP_PKEY_ASN1_METHOD object.

EVP_PKEY_get0_asn1() finds the EVP_PKEY_ASN1_METHOD associated with the key pkey.

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an EVP_PKEY_ASN1_METHOD object otherwise.

EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error, or 1 on success.

EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant EVP_PKEY_ASN1_METHOD object otherwise.

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#history","title":"HISTORY","text":"

The signature of the pub_decode functional argument of EVP_PKEY_asn1_set_public() has changed in OpenSSL 3.0 so its pub parameter is now constified.

"},{"location":"man3/EVP_PKEY_ASN1_METHOD/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2024 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.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/","title":"EVP_PKEY_CTX_ctrl","text":""},{"location":"man3/EVP_PKEY_CTX_ctrl/#name","title":"NAME","text":"

EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, EVP_PKEY_CTX_md, EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_get_signature_md, EVP_PKEY_CTX_set_mac_key, EVP_PKEY_CTX_set_group_name, EVP_PKEY_CTX_get_group_name, EVP_PKEY_CTX_set_rsa_padding, EVP_PKEY_CTX_get_rsa_padding, EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_get_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_keygen_bits, EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set1_rsa_keygen_pubexp, EVP_PKEY_CTX_set_rsa_keygen_primes, EVP_PKEY_CTX_set_rsa_mgf1_md_name, EVP_PKEY_CTX_set_rsa_mgf1_md, EVP_PKEY_CTX_get_rsa_mgf1_md, EVP_PKEY_CTX_get_rsa_mgf1_md_name, EVP_PKEY_CTX_set_rsa_oaep_md_name, EVP_PKEY_CTX_set_rsa_oaep_md, EVP_PKEY_CTX_get_rsa_oaep_md, EVP_PKEY_CTX_get_rsa_oaep_md_name, EVP_PKEY_CTX_set0_rsa_oaep_label, EVP_PKEY_CTX_get0_rsa_oaep_label, EVP_PKEY_CTX_set_dsa_paramgen_bits, EVP_PKEY_CTX_set_dsa_paramgen_q_bits, EVP_PKEY_CTX_set_dsa_paramgen_md, EVP_PKEY_CTX_set_dsa_paramgen_md_props, EVP_PKEY_CTX_set_dsa_paramgen_gindex, EVP_PKEY_CTX_set_dsa_paramgen_type, EVP_PKEY_CTX_set_dsa_paramgen_seed, EVP_PKEY_CTX_set_dh_paramgen_prime_len, EVP_PKEY_CTX_set_dh_paramgen_subprime_len, EVP_PKEY_CTX_set_dh_paramgen_generator, EVP_PKEY_CTX_set_dh_paramgen_type, EVP_PKEY_CTX_set_dh_paramgen_gindex, EVP_PKEY_CTX_set_dh_paramgen_seed, EVP_PKEY_CTX_set_dh_rfc5114, EVP_PKEY_CTX_set_dhx_rfc5114, EVP_PKEY_CTX_set_dh_pad, EVP_PKEY_CTX_set_dh_nid, EVP_PKEY_CTX_set_dh_kdf_type, EVP_PKEY_CTX_get_dh_kdf_type, EVP_PKEY_CTX_set0_dh_kdf_oid, EVP_PKEY_CTX_get0_dh_kdf_oid, EVP_PKEY_CTX_set_dh_kdf_md, EVP_PKEY_CTX_get_dh_kdf_md, EVP_PKEY_CTX_set_dh_kdf_outlen, EVP_PKEY_CTX_get_dh_kdf_outlen, EVP_PKEY_CTX_set0_dh_kdf_ukm, EVP_PKEY_CTX_get0_dh_kdf_ukm, EVP_PKEY_CTX_set_ec_paramgen_curve_nid, EVP_PKEY_CTX_set_ec_param_enc, EVP_PKEY_CTX_set_ecdh_cofactor_mode, EVP_PKEY_CTX_get_ecdh_cofactor_mode, EVP_PKEY_CTX_set_ecdh_kdf_type, EVP_PKEY_CTX_get_ecdh_kdf_type, EVP_PKEY_CTX_set_ecdh_kdf_md, EVP_PKEY_CTX_get_ecdh_kdf_md, EVP_PKEY_CTX_set_ecdh_kdf_outlen, EVP_PKEY_CTX_get_ecdh_kdf_outlen, EVP_PKEY_CTX_set0_ecdh_kdf_ukm, EVP_PKEY_CTX_get0_ecdh_kdf_ukm, EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len, EVP_PKEY_CTX_set_kem_op - algorithm specific control operations

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,\n                      int cmd, int p1, void *p2);\nint EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,\n                             int cmd, uint64_t value);\nint EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,\n                          const char *value);\n\nint EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md);\n\nint EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);\n\nint EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key,\n                             int len);\nint EVP_PKEY_CTX_set_group_name(EVP_PKEY_CTX *ctx, const char *name);\nint EVP_PKEY_CTX_get_group_name(EVP_PKEY_CTX *ctx, char *name, size_t namelen);\n\nint EVP_PKEY_CTX_set_kem_op(EVP_PKEY_CTX *ctx, const char *op);\n\n#include <openssl/rsa.h>\n\nint EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);\nint EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad);\nint EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int saltlen);\nint EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *saltlen);\nint EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);\nint EVP_PKEY_CTX_set1_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);\nint EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes);\nint EVP_PKEY_CTX_set_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, const char *mdname,\n                                    const char *mdprops);\nint EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);\nint EVP_PKEY_CTX_get_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, char *name,\n                                      size_t namelen);\nint EVP_PKEY_CTX_set_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, const char *mdname,\n                                      const char *mdprops);\nint EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);\nint EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name,\n                                      size_t namelen);\nint EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, void *label,\n                                     int len);\nint EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);\n\n#include <openssl/dsa.h>\n\nint EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);\nint EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);\nint EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_set_dsa_paramgen_md_props(EVP_PKEY_CTX *ctx,\n                                           const char *md_name,\n                                           const char *md_properties);\nint EVP_PKEY_CTX_set_dsa_paramgen_type(EVP_PKEY_CTX *ctx, const char *name);\nint EVP_PKEY_CTX_set_dsa_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex);\nint EVP_PKEY_CTX_set_dsa_paramgen_seed(EVP_PKEY_CTX *ctx,\n                                       const unsigned char *seed,\n                                       size_t seedlen);\n\n#include <openssl/dh.h>\n\nint EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);\nint EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len);\nint EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);\nint EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type);\nint EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);\nint EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);\nint EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);\nint EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);\nint EVP_PKEY_CTX_set_dh_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex);\nint EVP_PKEY_CTX_set_dh_paramgen_seed(EVP_PKEY_CTX *ctx,\n                                       const unsigned char *seed,\n                                       size_t seedlen);\nint EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);\nint EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid);\nint EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid);\nint EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);\nint EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);\nint EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);\nint EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);\n\n#include <openssl/ec.h>\n\nint EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);\nint EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);\nint EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode);\nint EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);\nint EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);\nint EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);\nint EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);\nint EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);\nint EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);\n\nint EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);\nint EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);\nint EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/rsa.h>\n\nint EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);\n\n#include <openssl/dh.h>\n\nint EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);\n\n#include <openssl/ec.h>\n\nint EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);\n
"},{"location":"man3/EVP_PKEY_CTX_ctrl/#description","title":"DESCRIPTION","text":"

EVP_PKEY_CTX_ctrl() sends a control operation to the context ctx. The key type used must match keytype if it is not -1. The parameter optype is a mask indicating which operations the control can be applied to. The control command is indicated in cmd and any additional arguments in p1 and p2.

For cmd = EVP_PKEY_CTRL_SET_MAC_KEY, p1 is the length of the MAC key, and p2 is the MAC key. This is used by Poly1305, SipHash, HMAC and CMAC.

Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will instead call one of the algorithm specific functions below.

EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a uint64 value as p2 to EVP_PKEY_CTX_ctrl().

EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm specific control operation to a context ctx in string form. This is intended to be used for options specified on the command line or in text files. The commands supported are documented in the openssl utility command line pages for the option -pkeyopt which is supported by the pkeyutl, genpkey and req commands.

EVP_PKEY_CTX_md() sends a message digest control operation to the context ctx. The message digest is specified by its name md.

EVP_PKEY_CTX_set_signature_md() sets the message digest type used in a signature. It can be used in the RSA, DSA and ECDSA algorithms.

EVP_PKEY_CTX_get_signature_md()gets the message digest type used in a signature. It can be used in the RSA, DSA and ECDSA algorithms.

Key generation typically involves setting up parameters to be used and generating the private and public key data. Some algorithm implementations allow private key data to be set explicitly using EVP_PKEY_CTX_set_mac_key(). In this case key generation is simply the process of setting up the parameters for the key and then setting the raw key data to the value explicitly. Normally applications would call EVP_PKEY_new_raw_private_key(3) or similar functions instead.

EVP_PKEY_CTX_set_mac_key() can be used with any of the algorithms supported by the EVP_PKEY_new_raw_private_key(3) function.

EVP_PKEY_CTX_set_group_name() sets the group name to name for parameter and key generation. For example for EC keys this will set the curve name and for DH keys it will set the name of the finite field group.

EVP_PKEY_CTX_get_group_name() finds the group name that's currently set with ctx, and writes it to the location that name points at, as long as its size namelen is large enough to store that name, including a terminating NUL byte.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#rsa-parameters","title":"RSA parameters","text":"

EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for ctx. The pad parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, RSA_NO_PADDING for no padding, RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), RSA_X931_PADDING for X9.31 padding (signature operations only), RSA_PKCS1_PSS_PADDING (sign and verify only) and RSA_PKCS1_WITH_TLS_PADDING for TLS RSA ClientKeyExchange message padding (decryption only).

Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() is used. If this function is called for PKCS#1 padding the plaintext buffer is an actual digest value and is encapsulated in a DigestInfo structure according to PKCS#1 when signing and this structure is expected (and stripped off) when verifying. If this control is not used with RSA and PKCS#1 padding then the supplied data is used directly and not encapsulated. In the case of X9.31 padding for RSA the algorithm identifier byte is added or checked and removed if this control is called. If it is not called then the first byte of the plaintext buffer is expected to be the algorithm identifier byte.

EVP_PKEY_CTX_get_rsa_padding() gets the RSA padding mode for ctx.

EVP_PKEY_CTX_set_rsa_pss_saltlen() sets the RSA PSS salt length to saltlen. As its name implies it is only supported for PSS padding. If this function is not called then the salt length is maximized up to the digest length when signing and auto detection when verifying. Four special values are supported:

EVP_PKEY_CTX_get_rsa_pss_saltlen() gets the RSA PSS salt length for ctx. The padding mode must already have been set to RSA_PKCS1_PSS_PADDING.

EVP_PKEY_CTX_set_rsa_keygen_bits() sets the RSA key length for RSA key generation to bits. If not specified 2048 bits is used.

EVP_PKEY_CTX_set1_rsa_keygen_pubexp() sets the public exponent value for RSA key generation to the value stored in pubexp. Currently it should be an odd integer. In accordance with the OpenSSL naming convention, the pubexp pointer must be freed independently of the EVP_PKEY_CTX (ie, it is internally copied). If not specified 65537 is used.

EVP_PKEY_CTX_set_rsa_keygen_pubexp() does the same as EVP_PKEY_CTX_set1_rsa_keygen_pubexp() except that there is no internal copy and therefore pubexp should not be modified or freed after the call.

EVP_PKEY_CTX_set_rsa_keygen_primes() sets the number of primes for RSA key generation to primes. If not specified 2 is used.

EVP_PKEY_CTX_set_rsa_mgf1_md_name() sets the MGF1 digest for RSA padding schemes to the digest named mdname. If the RSA algorithm implementation for the selected provider supports it then the digest will be fetched using the properties mdprops. If not explicitly set the signing digest is used. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING or RSA_PKCS1_PSS_PADDING.

EVP_PKEY_CTX_set_rsa_mgf1_md() does the same as EVP_PKEY_CTX_set_rsa_mgf1_md_name() except that the name of the digest is inferred from the supplied md and it is not possible to specify any properties.

EVP_PKEY_CTX_get_rsa_mgf1_md_name() gets the name of the MGF1 digest algorithm for ctx. If not explicitly set the signing digest is used. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING or RSA_PKCS1_PSS_PADDING.

EVP_PKEY_CTX_get_rsa_mgf1_md() does the same as EVP_PKEY_CTX_get_rsa_mgf1_md_name() except that it returns a pointer to an EVP_MD object instead. Note that only known, built-in EVP_MD objects will be returned. The EVP_MD object may be NULL if the digest is not one of these (such as a digest only implemented in a third party provider).

EVP_PKEY_CTX_set_rsa_oaep_md_name() sets the message digest type used in RSA OAEP to the digest named mdname. If the RSA algorithm implementation for the selected provider supports it then the digest will be fetched using the properties mdprops. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING.

EVP_PKEY_CTX_set_rsa_oaep_md() does the same as EVP_PKEY_CTX_set_rsa_oaep_md_name() except that the name of the digest is inferred from the supplied md and it is not possible to specify any properties.

EVP_PKEY_CTX_get_rsa_oaep_md_name() gets the message digest algorithm name used in RSA OAEP and stores it in the buffer name which is of size namelen. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING. The buffer should be sufficiently large for any expected digest algorithm names or the function will fail.

EVP_PKEY_CTX_get_rsa_oaep_md() does the same as EVP_PKEY_CTX_get_rsa_oaep_md_name() except that it returns a pointer to an EVP_MD object instead. Note that only known, built-in EVP_MD objects will be returned. The EVP_MD object may be NULL if the digest is not one of these (such as a digest only implemented in a third party provider).

EVP_PKEY_CTX_set0_rsa_oaep_label() sets the RSA OAEP label to binary data label and its length in bytes to len. If label is NULL or len is 0, the label is cleared. The library takes ownership of the label so the caller should not free the original memory pointed to by label. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING.

EVP_PKEY_CTX_get0_rsa_oaep_label() gets the RSA OAEP label to label. The return value is the label length. The padding mode must have been set to RSA_PKCS1_OAEP_PADDING. The resulting pointer is owned by the library and should not be freed by the caller.

RSA_PKCS1_WITH_TLS_PADDING is used when decrypting an RSA encrypted TLS pre-master secret in a TLS ClientKeyExchange message. It is the same as RSA_PKCS1_PADDING except that it additionally verifies that the result is the correct length and the first two bytes are the protocol version initially requested by the client. If the encrypted content is publicly invalid then the decryption will fail. However, if the padding checks fail then decryption will still appear to succeed but a random TLS premaster secret will be returned instead. This padding mode accepts two parameters which can be set using the EVP_PKEY_CTX_set_params(3) function. These are OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be unsigned integers. Normally only the first of these will be set and represents the TLS protocol version that was first requested by the client (e.g. 0x0303 for TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the negotiated protocol version instead of the protocol version first requested. If this behaviour should be tolerated then OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual negotiated protocol version. Otherwise it should be left unset.

Similarly to the RSA_PKCS1_WITH_TLS_PADDING above, since OpenSSL version 3.2.0, the use of RSA_PKCS1_PADDING will return a randomly generated message instead of padding errors in case padding checks fail. Applications that want to remain secure while using earlier versions of OpenSSL, or a provider that doesn't implement the implicit rejection mechanism, still need to handle both the error code from the RSA decryption operation and the returned message in a side channel secure manner. This protection against Bleichenbacher attacks can be disabled by setting OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION (an unsigned integer) to 0.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#dsa-parameters","title":"DSA parameters","text":"

EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used for DSA parameter generation to nbits. If not specified, 2048 is used.

EVP_PKEY_CTX_set_dsa_paramgen_q_bits() sets the number of bits in the subprime parameter q for DSA parameter generation to qbits. If not specified, 224 is used. If a digest function is specified below, this parameter is ignored and instead, the number of bits in q matches the size of the digest.

EVP_PKEY_CTX_set_dsa_paramgen_md() sets the digest function used for DSA parameter generation to md. If not specified, one of SHA-1, SHA-224, or SHA-256 is selected to match the bit length of q above.

EVP_PKEY_CTX_set_dsa_paramgen_md_props() sets the digest function used for DSA parameter generation using md_name and md_properties to retrieve the digest from a provider. If not specified, md_name will be set to one of SHA-1, SHA-224, or SHA-256 depending on the bit length of q above. md_properties is a property query string that has a default value of '' if not specified.

EVP_PKEY_CTX_set_dsa_paramgen_gindex() sets the gindex used by the generator G. The default value is -1 which uses unverifiable g, otherwise a positive value uses verifiable g. This value must be saved if key validation of g is required, since it is not part of a persisted key.

EVP_PKEY_CTX_set_dsa_paramgen_seed() sets the seed to use for generation rather than using a randomly generated value for the seed. This is useful for testing purposes only and can fail if the seed does not produce primes for both p & q on its first iteration. This value must be saved if key validation of p, q, and verifiable g are required, since it is not part of a persisted key.

EVP_PKEY_CTX_set_dsa_paramgen_type() sets the generation type to use FIPS186-4 generation if name is \"fips186_4\", or FIPS186-2 generation if name is \"fips186_2\". The default value for the default provider is \"fips186_2\". The default value for the FIPS provider is \"fips186_4\".

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#dh-parameters","title":"DH parameters","text":"

EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH prime parameter p for DH parameter generation. If this function is not called then 2048 is used. Only accepts lengths greater than or equal to 256.

EVP_PKEY_CTX_set_dh_paramgen_subprime_len() sets the length of the DH optional subprime parameter q for DH parameter generation. The default is 256 if the prime is at least 2048 bits long or 160 otherwise. The DH paramgen type must have been set to \"fips186_4\".

EVP_PKEY_CTX_set_dh_paramgen_generator() sets DH generator to gen for DH parameter generation. If not specified 2 is used.

EVP_PKEY_CTX_set_dh_paramgen_type() sets the key type for DH parameter generation. The supported parameters are:

The default in the default provider is DH_PARAMGEN_TYPE_GENERATOR for the \"DH\" keytype, and DH_PARAMGEN_TYPE_FIPS_186_2 for the \"DHX\" keytype. In the FIPS provider the default value is DH_PARAMGEN_TYPE_GROUP for the \"DH\" keytype and <DH_PARAMGEN_TYPE_FIPS_186_4 for the \"DHX\" keytype.

EVP_PKEY_CTX_set_dh_paramgen_gindex() sets the gindex used by the generator G. The default value is -1 which uses unverifiable g, otherwise a positive value uses verifiable g. This value must be saved if key validation of g is required, since it is not part of a persisted key.

EVP_PKEY_CTX_set_dh_paramgen_seed() sets the seed to use for generation rather than using a randomly generated value for the seed. This is useful for testing purposes only and can fail if the seed does not produce primes for both p & q on its first iteration. This value must be saved if key validation of p, q, and verifiable g are required, since it is not part of a persisted key.

EVP_PKEY_CTX_set_dh_pad() sets the DH padding mode. If pad is 1 the shared secret is padded with zeros up to the size of the DH prime p. If pad is zero (the default) then no padding is performed.

EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to nid as defined in RFC7919 or RFC3526. The nid parameter must be NID_ffdhe2048, NID_ffdhe3072, NID_ffdhe4096, NID_ffdhe6144, NID_ffdhe8192, NID_modp_1536, NID_modp_2048, NID_modp_3072, NID_modp_4096, NID_modp_6144, NID_modp_8192 or NID_undef to clear the stored value. This function can be called during parameter or key generation. The nid parameter and the rfc5114 parameter are mutually exclusive.

EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() both set the DH parameters to the values defined in RFC5114. The rfc5114 parameter must be 1, 2 or 3 corresponding to RFC5114 sections 2.1, 2.2 and 2.3. or 0 to clear the stored value. This macro can be called during parameter generation. The ctx must have a key type of EVP_PKEY_DHX. The rfc5114 parameter and the nid parameter are mutually exclusive.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#dh-key-derivation-function-parameters","title":"DH key derivation function parameters","text":"

Note that all of the following functions require that the ctx parameter has a private key type of EVP_PKEY_DHX. When using key derivation, the output of EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret. The KDF output is typically used as a Key Encryption Key (KEK) that in turn encrypts a Content Encryption Key (CEK).

EVP_PKEY_CTX_set_dh_kdf_type() sets the key derivation function type to kdf for DH key derivation. Possible values are EVP_PKEY_DH_KDF_NONE and EVP_PKEY_DH_KDF_X9_42 which uses the key derivation specified in RFC2631 (based on the keying algorithm described in X9.42). When using key derivation, the kdf_oid, kdf_md and kdf_outlen parameters must also be specified.

EVP_PKEY_CTX_get_dh_kdf_type() gets the key derivation function type for ctx used for DH key derivation. Possible values are EVP_PKEY_DH_KDF_NONE and EVP_PKEY_DH_KDF_X9_42.

EVP_PKEY_CTX_set0_dh_kdf_oid() sets the key derivation function object identifier to oid for DH key derivation. This OID should identify the algorithm to be used with the Content Encryption Key. The library takes ownership of the object identifier so the caller should not free the original memory pointed to by oid.

EVP_PKEY_CTX_get0_dh_kdf_oid() gets the key derivation function oid for ctx used for DH key derivation. The resulting pointer is owned by the library and should not be freed by the caller.

EVP_PKEY_CTX_set_dh_kdf_md() sets the key derivation function message digest to md for DH key derivation. Note that RFC2631 specifies that this digest should be SHA1 but OpenSSL tolerates other digests.

EVP_PKEY_CTX_get_dh_kdf_md() gets the key derivation function message digest for ctx used for DH key derivation.

EVP_PKEY_CTX_set_dh_kdf_outlen() sets the key derivation function output length to len for DH key derivation.

EVP_PKEY_CTX_get_dh_kdf_outlen() gets the key derivation function output length for ctx used for DH key derivation.

EVP_PKEY_CTX_set0_dh_kdf_ukm() sets the user key material to ukm and its length to len for DH key derivation. This parameter is optional and corresponds to the partyAInfo field in RFC2631 terms. The specification requires that it is 512 bits long but this is not enforced by OpenSSL. The library takes ownership of the user key material so the caller should not free the original memory pointed to by ukm.

EVP_PKEY_CTX_get0_dh_kdf_ukm() gets the user key material for ctx. The return value is the user key material length. The resulting pointer is owned by the library and should not be freed by the caller.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#ec-parameters","title":"EC parameters","text":"

Use EVP_PKEY_CTX_set_group_name() (described above) to set the curve name to name for parameter and key generation.

EVP_PKEY_CTX_set_ec_paramgen_curve_nid() does the same as EVP_PKEY_CTX_set_group_name(), but is specific to EC and uses a nid rather than a name string.

For EC parameter generation, one of EVP_PKEY_CTX_set_group_name() or EVP_PKEY_CTX_set_ec_paramgen_curve_nid() must be called or an error occurs because there is no default curve. These function can also be called to set the curve explicitly when generating an EC key.

EVP_PKEY_CTX_get_group_name() (described above) can be used to obtain the curve name that's currently set with ctx.

EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to param_enc when generating EC parameters or an EC key. The encoding can be OPENSSL_EC_EXPLICIT_CURVE for explicit parameters (the default in versions of OpenSSL before 1.1.0) or OPENSSL_EC_NAMED_CURVE to use named curve form. For maximum compatibility the named curve form should be used. Note: the OPENSSL_EC_NAMED_CURVE value was added in OpenSSL 1.1.0; previous versions should use 0 instead.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#ecdh-parameters","title":"ECDH parameters","text":"

EVP_PKEY_CTX_set_ecdh_cofactor_mode() sets the cofactor mode to cofactor_mode for ECDH key derivation. Possible values are 1 to enable cofactor key derivation, 0 to disable it and -1 to clear the stored cofactor mode and fallback to the private key cofactor mode.

EVP_PKEY_CTX_get_ecdh_cofactor_mode() returns the cofactor mode for ctx used for ECDH key derivation. Possible values are 1 when cofactor key derivation is enabled and 0 otherwise.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#ecdh-key-derivation-function-parameters","title":"ECDH key derivation function parameters","text":"

EVP_PKEY_CTX_set_ecdh_kdf_type() sets the key derivation function type to kdf for ECDH key derivation. Possible values are EVP_PKEY_ECDH_KDF_NONE and EVP_PKEY_ECDH_KDF_X9_63 which uses the key derivation specified in X9.63. When using key derivation, the kdf_md and kdf_outlen parameters must also be specified.

EVP_PKEY_CTX_get_ecdh_kdf_type() returns the key derivation function type for ctx used for ECDH key derivation. Possible values are EVP_PKEY_ECDH_KDF_NONE and EVP_PKEY_ECDH_KDF_X9_63.

EVP_PKEY_CTX_set_ecdh_kdf_md() sets the key derivation function message digest to md for ECDH key derivation. Note that X9.63 specifies that this digest should be SHA1 but OpenSSL tolerates other digests.

EVP_PKEY_CTX_get_ecdh_kdf_md() gets the key derivation function message digest for ctx used for ECDH key derivation.

EVP_PKEY_CTX_set_ecdh_kdf_outlen() sets the key derivation function output length to len for ECDH key derivation.

EVP_PKEY_CTX_get_ecdh_kdf_outlen() gets the key derivation function output length for ctx used for ECDH key derivation.

EVP_PKEY_CTX_set0_ecdh_kdf_ukm() sets the user key material to ukm for ECDH key derivation. This parameter is optional and corresponds to the shared info in X9.63 terms. The library takes ownership of the user key material so the caller should not free the original memory pointed to by ukm.

EVP_PKEY_CTX_get0_ecdh_kdf_ukm() gets the user key material for ctx. The return value is the user key material length. The resulting pointer is owned by the library and should not be freed by the caller.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#other-parameters","title":"Other parameters","text":"

EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() are used to manipulate the special identifier field for specific signature algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by id with the length id_len to the library. The library takes a copy of the id so that the caller can safely free the original memory pointed to by id. EVP_PKEY_CTX_get1_id_len() returns the length of the ID set via a previous call to EVP_PKEY_CTX_set1_id(). The length is usually used to allocate adequate memory for further calls to EVP_PKEY_CTX_get1_id(). EVP_PKEY_CTX_get1_id() returns the previously set ID value to caller in id. The caller should allocate adequate memory space for the id before calling EVP_PKEY_CTX_get1_id().

EVP_PKEY_CTX_set_kem_op() sets the KEM operation to run. This can be set after EVP_PKEY_encapsulate_init() or EVP_PKEY_decapsulate_init() to select the kem operation. For the key types that support encapsulation and don't have the default operation, e.g. RSA, this function must be called before EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate(). The supported values for the built-in algorithms are enumerated in EVP_KEM-RSA(7), EVP_KEM-EC(7), EVP_KEM-X25519(7), and EVP_KEM-X448(7).

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#return-values","title":"RETURN VALUES","text":"

All other functions described on this page return a positive value for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_set_params(3), EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3), EVP_PKEY_keygen(3) EVP_PKEY_encapsulate(3) EVP_PKEY_decapsulate(3)

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#history","title":"HISTORY","text":"

EVP_PKEY_CTX_get_rsa_oaep_md_name(), EVP_PKEY_CTX_get_rsa_mgf1_md_name(), EVP_PKEY_CTX_set_rsa_mgf1_md_name(), EVP_PKEY_CTX_set_rsa_oaep_md_name(), EVP_PKEY_CTX_set_dsa_paramgen_md_props(), EVP_PKEY_CTX_set_dsa_paramgen_gindex(), EVP_PKEY_CTX_set_dsa_paramgen_type(), EVP_PKEY_CTX_set_dsa_paramgen_seed(), EVP_PKEY_CTX_set_group_name() and EVP_PKEY_CTX_get_group_name() were added in OpenSSL 3.0.

The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.

In OpenSSL 1.1.1 and below the functions were mostly macros. From OpenSSL 3.0 they are all functions.

EVP_PKEY_CTX_set_rsa_keygen_pubexp(), EVP_PKEY_CTX_get0_dh_kdf_ukm(), and EVP_PKEY_CTX_get0_ecdh_kdf_ukm() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_ctrl/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/","title":"EVP_PKEY_CTX_get0_libctx","text":""},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#name","title":"NAME","text":"

EVP_PKEY_CTX_get0_libctx, EVP_PKEY_CTX_get0_propq, EVP_PKEY_CTX_get0_provider - functions for getting diverse information from an EVP_PKEY_CTX

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nOSSL_LIB_CTX *EVP_PKEY_CTX_get0_libctx(EVP_PKEY_CTX *ctx);\nconst char *EVP_PKEY_CTX_get0_propq(const EVP_PKEY_CTX *ctx);\nconst OSSL_PROVIDER *EVP_PKEY_CTX_get0_provider(const EVP_PKEY_CTX *ctx);\n
"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#description","title":"DESCRIPTION","text":"

EVP_PKEY_CTX_get0_libctx() and EVP_PKEY_CTX_get0_propq() obtain the OSSL_LIB_CTX and property query string values respectively that were associated with the EVP_PKEY_CTX when it was constructed.

EVP_PKEY_CTX_get0_provider() returns the provider associated with the ongoing EVP_PKEY_CTX operation. If the operation is performed by en ENGINE, this function returns NULL.

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_CTX_get0_libctx() and EVP_PKEY_CTX_get0_propq() functions return the OSSL_LIB_CTX and property query string associated with the EVP_PKEY_CTX or NULL if they are not set. The returned values should not be freed by the caller.

EVP_PKEY_CTX_get0_provider() returns a provider if an operation performed by a provider is ongoing, otherwise NULL.

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3)

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#history","title":"HISTORY","text":"

All functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_get0_libctx/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/","title":"EVP_PKEY_CTX_get0_pkey","text":""},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#name","title":"NAME","text":"

EVP_PKEY_CTX_get0_pkey, EVP_PKEY_CTX_get0_peerkey - functions for accessing the EVP_PKEY associated with an EVP_PKEY_CTX

"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx);\nEVP_PKEY *EVP_PKEY_CTX_get0_peerkey(EVP_PKEY_CTX *ctx);\n
"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#description","title":"DESCRIPTION","text":"

EVP_PKEY_CTX_get0_pkey() is used to access the EVP_PKEY associated with the given EVP_PKEY_CTX ctx. The EVP_PKEY obtained is the one used for creating the EVP_PKEY_CTX using either EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3).

EVP_PKEY_CTX_get0_peerkey() is used to access the peer EVP_PKEY associated with the given EVP_PKEY_CTX ctx. The peer EVP_PKEY obtained is the one set using either EVP_PKEY_derive_set_peer(3) or EVP_PKEY_derive_set_peer_ex(3).

"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_CTX_get0_pkey() returns the EVP_PKEY associated with the EVP_PKEY_CTX or NULL if it is not set.

EVP_PKEY_CTX_get0_peerkey() returns the peer EVP_PKEY associated with the EVP_PKEY_CTX or NULL if it is not set.

The returned EVP_PKEY objects are owned by the EVP_PKEY_CTX, and therefore should not explicitly be freed by the caller.

These functions do not affect the EVP_PKEY reference count. They merely act as getter functions, and should be treated as such.

"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_new_from_pkey(3), EVP_PKEY_derive_set_peer(3), EVP_PKEY_derive_set_peer_ex(3)

"},{"location":"man3/EVP_PKEY_CTX_get0_pkey/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2023 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.

"},{"location":"man3/EVP_PKEY_CTX_get_algor/","title":"EVP_PKEY_CTX_get_algor","text":""},{"location":"man3/EVP_PKEY_CTX_get_algor/#name","title":"NAME","text":"

EVP_CIPHER_CTX_get_algor, EVP_CIPHER_CTX_get_algor_params, EVP_CIPHER_CTX_set_algor_params, EVP_PKEY_CTX_get_algor, EVP_PKEY_CTX_get_algor_params, EVP_PKEY_CTX_set_algor_params - pass AlgorithmIdentifier and its params to/from algorithm implementations

"},{"location":"man3/EVP_PKEY_CTX_get_algor/#synopsis","title":"SYNOPSIS","text":"
int EVP_TYPE_CTX_get_algor(EVP_TYPE_CTX *ctx, X509_ALGOR **alg);\nint EVP_TYPE_CTX_get_algor_params(EVP_TYPE_CTX *ctx, X509_ALGOR *alg);\nint EVP_TYPE_CTX_set_algor_params(EVP_TYPE_CTX *ctx, const X509_ALGOR *alg);\n
"},{"location":"man3/EVP_PKEY_CTX_get_algor/#description","title":"DESCRIPTION","text":"

In the description here and the \"SYNOPSIS\" above, TYPE is used as a placeholder for any EVP operation type.

EVP_TYPE_CTX_get_algor() attempts to retrieve a complete AlgorithmIdentifier from the EVP_TYPE implementation, and populates *alg with it. If alg is NULL, calling this function will serve to see if calling this function is supported at all by the EVP_TYPE implementation. If *alg is NULL, space will be allocated automatically, and assigned to *alg.

EVP_TYPE_CTX_get_algor_params() attempts to retrieve the parameters part of an AlgorithmIdentifier from the EVP_TYPE implementation, and populates alg-_parameters> with it. If _alg is NULL, calling this function will serve to see if calling this function is supported at all by the EVP_TYPE implementation. If alg->parameters is NULL, space will be allocated automatically, and assigned to alg->parameters. If alg->parameters is not NULL, its previous contents will be overwritten with the retrieved AlgorithmIdentifier parameters. Beware!

EVP_TYPE_CTX_set_algor_params() attempts to pass alg->parameters to the EVP_TYPE implementation. If alg is NULL, calling this function will serve to see if calling this function is supported at all by the EVP_TYPE implementation.

"},{"location":"man3/EVP_PKEY_CTX_get_algor/#return-values","title":"RETURN VALUES","text":"

All functions return 1 for success, and 0 or a negative number if an error occurs. In particular, -2 is returned when the function isn't supported by the EVP_TYPE implementation.

"},{"location":"man3/EVP_PKEY_CTX_get_algor/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_PKEY_CTX_new/","title":"EVP_PKEY_CTX_new","text":""},{"location":"man3/EVP_PKEY_CTX_new/#name","title":"NAME","text":"

EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_from_name, EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free, EVP_PKEY_CTX_is_a - public key algorithm context functions

"},{"location":"man3/EVP_PKEY_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);\nEVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);\nEVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OSSL_LIB_CTX *libctx,\n                                         const char *name,\n                                         const char *propquery);\nEVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx,\n                                         EVP_PKEY *pkey,\n                                         const char *propquery);\nEVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);\nvoid EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_CTX_is_a(EVP_PKEY_CTX *ctx, const char *keytype);\n
"},{"location":"man3/EVP_PKEY_CTX_new/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_CTX_new() function allocates public key algorithm context using the pkey key type and ENGINE e.

The EVP_PKEY_CTX_new_id() function allocates public key algorithm context using the key type specified by id and ENGINE e.

The EVP_PKEY_CTX_new_from_name() function allocates a public key algorithm context using the library context libctx (see OSSL_LIB_CTX(3)), the key type specified by name and the property query propquery. None of the arguments are duplicated, so they must remain unchanged for the lifetime of the returned EVP_PKEY_CTX or of any of its duplicates. Read further about the possible names in \"NOTES\" below.

The EVP_PKEY_CTX_new_from_pkey() function allocates a public key algorithm context using the library context libctx (see OSSL_LIB_CTX(3)) and the algorithm specified by pkey and the property query propquery. None of the arguments are duplicated, so they must remain unchanged for the lifetime of the returned EVP_PKEY_CTX or any of its duplicates.

EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_from_name() are normally used when no EVP_PKEY structure is associated with the operations, for example during parameter generation or key generation for some algorithms.

EVP_PKEY_CTX_dup() duplicates the context ctx. It is not supported for a keygen operation.

EVP_PKEY_CTX_free() frees up the context ctx. If ctx is NULL, nothing is done.

EVP_PKEY_is_a() checks if the key type associated with ctx is keytype.

"},{"location":"man3/EVP_PKEY_CTX_new/#notes","title":"NOTES","text":""},{"location":"man3/EVP_PKEY_CTX_new/#on-evp_pkey_ctx","title":"On EVP_PKEY_CTX","text":"

The EVP_PKEY_CTX structure is an opaque public key algorithm context used by the OpenSSL high-level public key API. Contexts MUST NOT be shared between threads: that is it is not permissible to use the same context simultaneously in two threads.

"},{"location":"man3/EVP_PKEY_CTX_new/#on-key-types","title":"On Key Types","text":"

We mention \"key type\" in this manual, which is the same as \"algorithm\" in most cases, allowing either term to be used interchangeably. There are algorithms where the key type and the algorithm of the operations that use the keys are not the same, such as EC keys being used for ECDSA and ECDH operations.

Key types are given in two different manners:

"},{"location":"man3/EVP_PKEY_CTX_new/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_dup() return either the newly allocated EVP_PKEY_CTX structure or NULL if an error occurred.

EVP_PKEY_CTX_free() does not return a value.

EVP_PKEY_CTX_is_a() returns 1 for true and 0 for false.

"},{"location":"man3/EVP_PKEY_CTX_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3)

"},{"location":"man3/EVP_PKEY_CTX_new/#history","title":"HISTORY","text":"

The EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() and EVP_PKEY_CTX_free() functions were added in OpenSSL 1.0.0.

The EVP_PKEY_CTX_new_from_name() and EVP_PKEY_CTX_new_from_pkey() functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/","title":"EVP_PKEY_CTX_set1_pbe_pass","text":""},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#name","title":"NAME","text":"

EVP_PKEY_CTX_set1_pbe_pass - generic KDF support functions

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/kdf.h>\n\nint EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,\n                               int passlen);\n
"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#description","title":"DESCRIPTION","text":"

These functions are generic support functions for all KDF algorithms.

EVP_PKEY_CTX_set1_pbe_pass() sets the password to the passlen first bytes from pass.

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#string-ctrls","title":"STRING CTRLS","text":"

There is also support for string based control operations via EVP_PKEY_CTX_ctrl_str(3). The password can be directly specified using the type parameter \"pass\" or given in hex encoding using the \"hexpass\" parameter.

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#return-values","title":"RETURN VALUES","text":"

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#history","title":"HISTORY","text":"

EVP_PKEY_CTX_set1_pbe_pass() was converted from a macro to a function in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_set1_pbe_pass/#copyright","title":"COPYRIGHT","text":"

Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/","title":"EVP_PKEY_CTX_set_hkdf_md","text":""},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#name","title":"NAME","text":"

EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info, EVP_PKEY_CTX_set_hkdf_mode - HMAC-based Extract-and-Expand key derivation algorithm

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/kdf.h>\n\nint EVP_PKEY_CTX_set_hkdf_mode(EVP_PKEY_CTX *pctx, int mode);\n\nint EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);\n\nint EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,\n                                int saltlen);\n\nint EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,\n                               int keylen);\n\nint EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,\n                                int infolen);\n
"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. HKDF follows the \"extract-then-expand\" paradigm, where the KDF logically consists of two modules. The first stage takes the input keying material and \"extracts\" from it a fixed-length pseudorandom key K. The second stage \"expands\" the key K into several additional pseudorandom keys (the output of the KDF).

EVP_PKEY_CTX_set_hkdf_mode() sets the mode for the HKDF operation. There are three modes that are currently defined:

EVP_PKEY_CTX_set_hkdf_md() sets the message digest associated with the HKDF.

EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to saltlen bytes of the buffer salt. Any existing value is replaced.

EVP_PKEY_CTX_set1_hkdf_key() sets the key to keylen bytes of the buffer key. Any existing value is replaced.

EVP_PKEY_CTX_add1_hkdf_info() sets the info value to infolen bytes of the buffer info. If a value is already set, it is appended to the existing value.

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#string-ctrls","title":"STRING CTRLS","text":"

HKDF also supports string based control operations via EVP_PKEY_CTX_ctrl_str(3). The type parameter \"md\" uses the supplied value as the name of the digest algorithm to use. The type parameter \"mode\" uses the values \"EXTRACT_AND_EXPAND\", \"EXTRACT_ONLY\" and \"EXPAND_ONLY\" to determine the mode to use. The type parameters \"salt\", \"key\" and \"info\" use the supplied value parameter as a seed, key or info value. The names \"hexsalt\", \"hexkey\" and \"hexinfo\" are similar except they take a hex string which is converted to binary.

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#notes","title":"NOTES","text":"

A context for HKDF can be obtained by calling:

EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);\n

The total length of the info buffer cannot exceed 2048 bytes in length: this should be more than enough for any normal use of HKDF.

The output length of an HKDF expand operation is specified via the length parameter to the EVP_PKEY_derive(3) function. Since the HKDF output length is variable, passing a NULL buffer as a means to obtain the requisite length is not meaningful with HKDF in any mode that performs an expand operation. Instead, the caller must allocate a buffer of the desired length, and pass that buffer to EVP_PKEY_derive(3) along with (a pointer initialized to) the desired length. Passing a NULL buffer to obtain the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY.

Optimised versions of HKDF can be implemented in an ENGINE.

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#return-values","title":"RETURN VALUES","text":"

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#examples","title":"EXAMPLES","text":"

This example derives 10 bytes using SHA-256 with the secret key \"secret\", salt value \"salt\" and info value \"label\":

EVP_PKEY_CTX *pctx;\nunsigned char out[10];\nsize_t outlen = sizeof(out);\npctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);\n\nif (EVP_PKEY_derive_init(pctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set1_hkdf_salt(pctx, \"salt\", 4) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set1_hkdf_key(pctx, \"secret\", 6) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_add1_hkdf_info(pctx, \"label\", 5) <= 0)\n    /* Error */\nif (EVP_PKEY_derive(pctx, out, &outlen) <= 0)\n    /* Error */\n
"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#conforming-to","title":"CONFORMING TO","text":"

RFC 5869

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#history","title":"HISTORY","text":"

All of the functions described here were converted from macros to functions in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_set_hkdf_md/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 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.

"},{"location":"man3/EVP_PKEY_CTX_set_params/","title":"EVP_PKEY_CTX_set_params","text":""},{"location":"man3/EVP_PKEY_CTX_set_params/#name","title":"NAME","text":"

EVP_PKEY_CTX_set_params, EVP_PKEY_CTX_settable_params, EVP_PKEY_CTX_get_params, EVP_PKEY_CTX_gettable_params - provider parameter passing operations

"},{"location":"man3/EVP_PKEY_CTX_set_params/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, const OSSL_PARAM *params);\nconst OSSL_PARAM *EVP_PKEY_CTX_settable_params(const EVP_PKEY_CTX *ctx);\nint EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);\nconst OSSL_PARAM *EVP_PKEY_CTX_gettable_params(const EVP_PKEY_CTX *ctx);\n
"},{"location":"man3/EVP_PKEY_CTX_set_params/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions allow transfer of arbitrary key parameters to and from providers. Not all parameters may be supported by all providers. See OSSL_PROVIDER(3) for more information on providers. The params field is a pointer to a list of OSSL_PARAM structures, terminated with a OSSL_PARAM_END(3) struct. See OSSL_PARAM(3) for information about passing parameters. These functions must only be called after the EVP_PKEY_CTX has been initialised for use in an operation. These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now calls these methods internally to interact with providers).

EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a constant OSSL_PARAM(3) array that describes the gettable and settable parameters for the current algorithm implementation, i.e. parameters that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() respectively. These functions must only be called after the EVP_PKEY_CTX has been initialised for use in an operation.

"},{"location":"man3/EVP_PKEY_CTX_set_params/#parameters","title":"Parameters","text":"

Examples of EVP_PKEY parameters include the following:

\"Common parameters\" in provider-keymgmt(7) \"Key Exchange parameters\" in provider-keyexch(7) \"Signature parameters\" in provider-signature(7)

\"Common RSA parameters\" in EVP_PKEY-RSA(7) \"RSA key generation parameters\" in EVP_PKEY-RSA(7) \"FFC parameters\" in EVP_PKEY-FFC(7) \"FFC key generation parameters\" in EVP_PKEY-FFC(7) \"DSA parameters\" in EVP_PKEY-DSA(7) \"DSA key generation parameters\" in EVP_PKEY-DSA(7) \"DH parameters\" in EVP_PKEY-DH(7) \"DH key generation parameters\" in EVP_PKEY-DH(7) \"Common EC parameters\" in EVP_PKEY-EC(7) \"Common X25519, X448, ED25519 and ED448 parameters\" in EVP_PKEY-X25519(7)

"},{"location":"man3/EVP_PKEY_CTX_set_params/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise. EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on error. It may also return NULL if there are no settable parameters available.

All other functions and macros described on this page return a positive value for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set_params/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3), EVP_PKEY_keygen(3)

"},{"location":"man3/EVP_PKEY_CTX_set_params/#history","title":"HISTORY","text":"

All functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_set_params/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2024 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.

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/","title":"EVP_PKEY_CTX_set_rsa_pss_keygen_md","text":""},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#name","title":"NAME","text":"

EVP_PKEY_CTX_set_rsa_pss_keygen_md, EVP_PKEY_CTX_set_rsa_pss_keygen_md_name, EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md, EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name, EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen - EVP_PKEY RSA-PSS algorithm support functions

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/rsa.h>\n\nint EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,\n                                       const EVP_MD *md);\nint EVP_PKEY_CTX_set_rsa_pss_keygen_md_name(EVP_PKEY_CTX *ctx,\n                                            const char *mdname,\n                                            const char *mdprops);\nint EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,\n                                            const EVP_MD *md);\nint EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name(EVP_PKEY_CTX *pctx,\n                                                 const char *mdname);\nint EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,\n                                            int saltlen);\n
"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#description","title":"DESCRIPTION","text":"

These are the functions that implement RSA-PSS(7).

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#signing-and-verification","title":"Signing and Verification","text":"

The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is returned if an attempt is made to set the padding mode to anything other than PSS. It is otherwise similar to the RSA version.

The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length. If the key has usage restrictions then an error is returned if an attempt is made to set the salt length below the minimum value. It is otherwise similar to the RSA operation except detection of the salt length (using RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has usage restrictions.

The EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_mgf1_md(3) functions are used to set the digest and MGF1 algorithms respectively. If the key has usage restrictions then an error is returned if an attempt is made to set the digest to anything other than the restricted value. Otherwise these are similar to the RSA versions.

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#key-generation","title":"Key Generation","text":"

As with RSA key generation the EVP_PKEY_CTX_set_rsa_keygen_bits() and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS: they have exactly the same meaning as for the RSA algorithm.

Optional parameter restrictions can be specified when generating a PSS key. If any restrictions are set (using the macros described below) then all parameters are restricted. For example, setting a minimum salt length also restricts the digest and MGF1 algorithms. If any restrictions are in place then they are reflected in the corresponding parameters of the public key when (for example) a certificate request is signed.

EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the generated key can use to md. EVP_PKEY_CTX_set_rsa_pss_keygen_md_name() does the same thing, but passes the algorithm by name rather than by EVP_MD.

EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the generated key can use to md. EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name() does the same thing, but passes the algorithm by name rather than by EVP_MD.

EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length to saltlen.

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#notes","title":"NOTES","text":"

A context for the RSA-PSS algorithm can be obtained by calling:

EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);\n
"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#return-values","title":"RETURN VALUES","text":"

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#see-also","title":"SEE ALSO","text":"

RSA-PSS(7), EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2021 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.

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/","title":"EVP_PKEY_CTX_set_scrypt_N","text":""},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#name","title":"NAME","text":"

EVP_PKEY_CTX_set1_scrypt_salt, EVP_PKEY_CTX_set_scrypt_N, EVP_PKEY_CTX_set_scrypt_r, EVP_PKEY_CTX_set_scrypt_p, EVP_PKEY_CTX_set_scrypt_maxmem_bytes - EVP_PKEY scrypt KDF support functions

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/kdf.h>\n\nint EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,\n                                  int saltlen);\n\nint EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);\n\nint EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);\n\nint EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);\n\nint EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx,\n                                         uint64_t maxmem);\n
"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#description","title":"DESCRIPTION","text":"

These functions are used to set up the necessary data to use the scrypt KDF. For more information on scrypt, see EVP_KDF-SCRYPT(7).

EVP_PKEY_CTX_set1_scrypt_salt() sets the saltlen bytes long salt value.

EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.

EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may maximally use, given in bytes. If RAM is exceeded because the load factors are chosen too high, the key derivation will fail.

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#string-ctrls","title":"STRING CTRLS","text":"

scrypt also supports string based control operations via EVP_PKEY_CTX_ctrl_str(3). Similarly, the salt can either be specified using the type parameter \"salt\" or in hex encoding by using the \"hexsalt\" parameter. The work factors N, r and p as well as maxmem_bytes can be set by using the parameters \"N\", \"r\", \"p\" and \"maxmem_bytes\", respectively.

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#notes","title":"NOTES","text":"

There is a newer generic API for KDFs, EVP_KDF(3), which is preferred over the EVP_PKEY method.

The scrypt KDF also uses EVP_PKEY_CTX_set1_pbe_pass() as well as the value from the string controls \"pass\" and \"hexpass\". See EVP_PKEY_CTX_set1_pbe_pass(3).

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#return-values","title":"RETURN VALUES","text":"

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#see-also","title":"SEE ALSO","text":"

EVP_KDF(3) EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#history","title":"HISTORY","text":"

All of the functions described here were converted from macros to functions in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_set_scrypt_N/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/","title":"EVP_PKEY_CTX_set_tls1_prf_md","text":""},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#name","title":"NAME","text":"

EVP_PKEY_CTX_set_tls1_prf_md, EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed - TLS PRF key derivation algorithm

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/kdf.h>\n\nint EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);\nint EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx,\n                                      unsigned char *sec, int seclen);\nint EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx,\n                                    unsigned char *seed, int seedlen);\n
"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_TLS1_PRF algorithm implements the PRF key derivation function for TLS. It has no associated private key and only implements key derivation using EVP_PKEY_derive(3).

EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF algorithm using both MD5 and SHA1 as used in TLS 1.0 and 1.1.

EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF to seclen bytes of the buffer sec. Any existing secret value is replaced and any seed is reset.

EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to seedlen bytes of seed. If a seed is already set it is appended to the existing value.

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#string-ctrls","title":"STRING CTRLS","text":"

The TLS PRF also supports string based control operations using EVP_PKEY_CTX_ctrl_str(3). The type parameter \"md\" uses the supplied value as the name of the digest algorithm to use. The type parameters \"secret\" and \"seed\" use the supplied value parameter as a secret or seed value. The names \"hexsecret\" and \"hexseed\" are similar except they take a hex string which is converted to binary.

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#notes","title":"NOTES","text":"

A context for the TLS PRF can be obtained by calling:

EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);\n

The digest, secret value and seed must be set before a key is derived or an error occurs.

The total length of all seeds cannot exceed 1024 bytes in length: this should be more than enough for any normal use of the TLS PRF.

The output length of the PRF is specified by the length parameter in the EVP_PKEY_derive() function. Since the output length is variable, setting the buffer to NULL is not meaningful for the TLS PRF.

Optimised versions of the TLS PRF can be implemented in an ENGINE.

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#return-values","title":"RETURN VALUES","text":"

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#examples","title":"EXAMPLES","text":"

This example derives 10 bytes using SHA-256 with the secret key \"secret\" and seed value \"seed\":

EVP_PKEY_CTX *pctx;\nunsigned char out[10];\nsize_t outlen = sizeof(out);\n\npctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);\nif (EVP_PKEY_derive_init(pctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, \"secret\", 6) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, \"seed\", 4) <= 0)\n    /* Error */\nif (EVP_PKEY_derive(pctx, out, &outlen) <= 0)\n    /* Error */\n
"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#history","title":"HISTORY","text":"

All of the functions described here were converted from macros to functions in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_CTX_set_tls1_prf_md/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PKEY_asn1_get_count/","title":"EVP_PKEY_asn1_get_count","text":""},{"location":"man3/EVP_PKEY_asn1_get_count/#name","title":"NAME","text":"

EVP_PKEY_asn1_find, EVP_PKEY_asn1_find_str, EVP_PKEY_asn1_get_count, EVP_PKEY_asn1_get0, EVP_PKEY_asn1_get0_info - enumerate public key ASN.1 methods

"},{"location":"man3/EVP_PKEY_asn1_get_count/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_asn1_get_count(void);\nconst EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_get0(int idx);\nconst EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pe, int type);\nconst EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str(ENGINE **pe,\n                                                   const char *str, int len);\nint EVP_PKEY_asn1_get0_info(int *ppkey_id, int *pkey_base_id,\n                            int *ppkey_flags, const char **pinfo,\n                            const char **ppem_str,\n                            const EVP_PKEY_ASN1_METHOD *ameth);\n
"},{"location":"man3/EVP_PKEY_asn1_get_count/#description","title":"DESCRIPTION","text":"

EVP_PKEY_asn1_count() returns a count of the number of public key ASN.1 methods available: it includes standard methods and any methods added by the application.

EVP_PKEY_asn1_get0() returns the public key ASN.1 method idx. The value of idx must be between zero and EVP_PKEY_asn1_get_count() - 1.

EVP_PKEY_asn1_find() looks up the EVP_PKEY_ASN1_METHOD with NID type. If pe isn't NULL, then it will look up an engine implementing a EVP_PKEY_ASN1_METHOD for the NID type and return that instead, and also set *pe to point at the engine that implements it.

EVP_PKEY_asn1_find_str() looks up the EVP_PKEY_ASN1_METHOD with PEM type string str. Just like EVP_PKEY_asn1_find(), if pe isn't NULL, then it will look up an engine implementing a EVP_PKEY_ASN1_METHOD for the NID type and return that instead, and also set *pe to point at the engine that implements it.

EVP_PKEY_asn1_get0_info() returns the public key ID, base public key ID (both NIDs), any flags, the method description and PEM type string associated with the public key ASN.1 method *ameth.

EVP_PKEY_asn1_count(), EVP_PKEY_asn1_get0(), EVP_PKEY_asn1_find() and EVP_PKEY_asn1_find_str() are not thread safe, but as long as all EVP_PKEY_ASN1_METHOD objects are added before the application gets threaded, using them is safe. See EVP_PKEY_asn1_add0(3).

"},{"location":"man3/EVP_PKEY_asn1_get_count/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_asn1_count() returns the number of available public key methods.

EVP_PKEY_asn1_get0() return a public key method or NULL if idx is out of range.

EVP_PKEY_asn1_get0_info() returns 0 on failure, 1 on success.

"},{"location":"man3/EVP_PKEY_asn1_get_count/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_asn1_new(3), EVP_PKEY_asn1_add0(3)

"},{"location":"man3/EVP_PKEY_asn1_get_count/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_PKEY_check/","title":"EVP_PKEY_check","text":""},{"location":"man3/EVP_PKEY_check/#name","title":"NAME","text":"

EVP_PKEY_check, EVP_PKEY_param_check, EVP_PKEY_param_check_quick, EVP_PKEY_public_check, EVP_PKEY_public_check_quick, EVP_PKEY_private_check, EVP_PKEY_pairwise_check - key and parameter validation functions

"},{"location":"man3/EVP_PKEY_check/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_check(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_param_check(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_param_check_quick(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_public_check(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_public_check_quick(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_private_check(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_pairwise_check(EVP_PKEY_CTX *ctx);\n
"},{"location":"man3/EVP_PKEY_check/#description","title":"DESCRIPTION","text":"

EVP_PKEY_param_check() validates the parameters component of the key given by ctx. This check will always succeed for key types that do not have parameters.

EVP_PKEY_param_check_quick() validates the parameters component of the key given by ctx like EVP_PKEY_param_check() does. However some algorithm implementations may offer a quicker form of validation that omits some checks in order to perform a lightweight sanity check of the key. If a quicker form is not provided then this function call does the same thing as EVP_PKEY_param_check().

EVP_PKEY_public_check() validates the public component of the key given by ctx.

EVP_PKEY_public_check_quick() validates the public component of the key given by ctx like EVP_PKEY_public_check() does. However some algorithm implementations may offer a quicker form of validation that omits some checks in order to perform a lightweight sanity check of the key. If a quicker form is not provided then this function call does the same thing as EVP_PKEY_public_check().

EVP_PKEY_private_check() validates the private component of the key given by ctx.

EVP_PKEY_pairwise_check() validates that the public and private components have the correct mathematical relationship to each other for the key given by ctx.

EVP_PKEY_check() is an alias for the EVP_PKEY_pairwise_check() function.

"},{"location":"man3/EVP_PKEY_check/#notes","title":"NOTES","text":"

Key validation used by the OpenSSL FIPS provider complies with the rules within SP800-56A and SP800-56B. For backwards compatibility reasons the OpenSSL default provider may use checks that are not as restrictive for certain key types. For further information see \"DSA key validation\" in EVP_PKEY-DSA(7), \"DH key validation\" in EVP_PKEY-DH(7), \"EC key validation\" in EVP_PKEY-EC(7) and \"RSA key validation\" in EVP_PKEY-RSA(7).

Refer to SP800-56A and SP800-56B for rules relating to when these functions should be called during key establishment. It is not necessary to call these functions after locally calling an approved key generation method, but may be required for assurance purposes when receiving keys from a third party.

The EVP_PKEY_pairwise_check() and EVP_PKEY_private_check() might not be bounded by any key size limits as private keys are not expected to be supplied by attackers. For that reason they might take an unbounded time if run on arbitrarily large keys.

"},{"location":"man3/EVP_PKEY_check/#return-values","title":"RETURN VALUES","text":"

All functions return 1 for success or others for failure. They return -2 if the operation is not supported for the specific algorithm.

"},{"location":"man3/EVP_PKEY_check/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_fromdata(3), EVP_PKEY-DH(7), EVP_PKEY-FFC(7), EVP_PKEY-DSA(7), EVP_PKEY-EC(7), EVP_PKEY-RSA(7),

"},{"location":"man3/EVP_PKEY_check/#history","title":"HISTORY","text":"

EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() were added in OpenSSL 1.1.1.

EVP_PKEY_param_check_quick(), EVP_PKEY_public_check_quick(), EVP_PKEY_private_check() and EVP_PKEY_pairwise_check() were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_check/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_PKEY_copy_parameters/","title":"EVP_PKEY_copy_parameters","text":""},{"location":"man3/EVP_PKEY_copy_parameters/#name","title":"NAME","text":"

EVP_PKEY_missing_parameters, EVP_PKEY_copy_parameters, EVP_PKEY_parameters_eq, EVP_PKEY_cmp_parameters, EVP_PKEY_eq, EVP_PKEY_cmp - public key parameter and comparison functions

"},{"location":"man3/EVP_PKEY_copy_parameters/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);\nint EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);\n\nint EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b);\nint EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b);\nint EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b);\n
"},{"location":"man3/EVP_PKEY_copy_parameters/#description","title":"DESCRIPTION","text":"

The function EVP_PKEY_missing_parameters() returns 1 if the public key parameters of pkey are missing and 0 if they are present or the algorithm doesn't use parameters.

The function EVP_PKEY_copy_parameters() copies the parameters from key from to key to. An error is returned if the parameters are missing in from or present in both from and to and mismatch. If the parameters in from and to are both present and match this function has no effect.

The function EVP_PKEY_parameters_eq() checks the parameters of keys a and b for equality.

The function EVP_PKEY_eq() checks the keys a and b for equality, including their parameters if they are available.

"},{"location":"man3/EVP_PKEY_copy_parameters/#notes","title":"NOTES","text":"

The main purpose of the functions EVP_PKEY_missing_parameters() and EVP_PKEY_copy_parameters() is to handle public keys in certificates where the parameters are sometimes omitted from a public key if they are inherited from the CA that signed it.

The deprecated functions EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() differ in their return values compared to other _cmp() functions. They are aliases for EVP_PKEY_eq() and EVP_PKEY_parameters_eq().

The function EVP_PKEY_cmp() previously only checked the key parameters (if there are any) and the public key, assuming that there always was a public key and that private key equality could be derived from that. Because it's no longer assumed that the private key in an EVP_PKEY(3) is always accompanied by a public key, the comparison can not rely on public key comparison alone.

Instead, EVP_PKEY_eq() (and therefore also EVP_PKEY_cmp()) now compares:

  1. the key parameters (if there are any)
  2. the public keys or the private keys of the two EVP_PKEYs, depending on what they both contain.
"},{"location":"man3/EVP_PKEY_copy_parameters/#return-values","title":"RETURN VALUES","text":"

The function EVP_PKEY_missing_parameters() returns 1 if the public key parameters of pkey are missing and 0 if they are present or the algorithm doesn't use parameters.

These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for failure.

The functions EVP_PKEY_cmp_parameters(), EVP_PKEY_parameters_eq(), EVP_PKEY_cmp() and EVP_PKEY_eq() return 1 if their inputs match, 0 if they don't match, -1 if the key types are different and -2 if the operation is not supported.

"},{"location":"man3/EVP_PKEY_copy_parameters/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_keygen(3)

"},{"location":"man3/EVP_PKEY_copy_parameters/#history","title":"HISTORY","text":"

The EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() functions were deprecated in OpenSSL 3.0.

The EVP_PKEY_eq() and EVP_PKEY_parameters_eq() were added in OpenSSL 3.0 to replace EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters().

"},{"location":"man3/EVP_PKEY_copy_parameters/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man3/EVP_PKEY_decapsulate/","title":"EVP_PKEY_decapsulate","text":""},{"location":"man3/EVP_PKEY_decapsulate/#name","title":"NAME","text":"

EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init, EVP_PKEY_decapsulate - Key decapsulation using a KEM algorithm with a private key

"},{"location":"man3/EVP_PKEY_decapsulate/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_auth_decapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpub,\n                                  const OSSL_PARAM params[]);\nint EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx,\n                         unsigned char *unwrapped, size_t *unwrappedlen,\n                         const unsigned char *wrapped, size_t wrappedlen);\n
"},{"location":"man3/EVP_PKEY_decapsulate/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_decapsulate_init() function initializes a private key algorithm context ctx for a decapsulation operation and then sets the params on the context in the same way as calling EVP_PKEY_CTX_set_params(3). Note that ctx usually is produced using EVP_PKEY_CTX_new_from_pkey(3), specifying the private key to use.

The EVP_PKEY_auth_decapsulate_init() function is similar to EVP_PKEY_decapsulate_init() but also passes an authpub authentication public key that is used during decapsulation.

The EVP_PKEY_decapsulate() function performs a private key decapsulation operation using ctx. The data to be decapsulated is specified using the wrapped and wrappedlen parameters. If unwrapped is NULL then the size of the output secret buffer is written to *unwrappedlen. If unwrapped is not NULL and the call is successful then the decapsulated secret data is written to unwrapped and the amount of data written to *unwrappedlen. Note that, if unwrappedlen is not NULL in this call, the value it points to must be initialised to the length of unwrapped, so that the call can validate it is of sufficient size to hold the result of the operation.

"},{"location":"man3/EVP_PKEY_decapsulate/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_decapsulate_init() algorithm-specific parameters for the operation may be set or modified using EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_PKEY_decapsulate/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_decapsulate_init(), EVP_PKEY_auth_decapsulate_init() and EVP_PKEY_decapsulate() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the private key algorithm.

"},{"location":"man3/EVP_PKEY_decapsulate/#examples","title":"EXAMPLES","text":"

Decapsulate data using RSA:

#include <openssl/evp.h>\n\n/*\n * NB: assumes rsa_priv_key is an RSA private key,\n * and that in, inlen are already set up to contain encapsulated data.\n */\n\nEVP_PKEY_CTX *ctx = NULL;\nsize_t secretlen = 0;\nunsigned char *secret = NULL;;\n\nctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL);\nif (ctx == NULL)\n    /* Error */\nif (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0)\n    /* Error */\n\n/* Set the mode - only 'RSASVE' is currently supported */\nif (EVP_PKEY_CTX_set_kem_op(ctx, \"RSASVE\") <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_decapsulate(ctx, NULL, &secretlen, in, inlen) <= 0)\n    /* Error */\n\nsecret = OPENSSL_malloc(secretlen);\nif (secret == NULL)\n    /* malloc failure */\n\n/* Decapsulated secret data is secretlen bytes long */\nif (EVP_PKEY_decapsulate(ctx, secret, &secretlen, in, inlen) <= 0)\n    /* Error */\n
"},{"location":"man3/EVP_PKEY_decapsulate/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new_from_pkey(3), EVP_PKEY_encapsulate(3), EVP_KEM-RSA(7), EVP_KEM-X25519(7), EVP_KEM-EC(7)

"},{"location":"man3/EVP_PKEY_decapsulate/#history","title":"HISTORY","text":"

The functions EVP_PKEY_decapsulate_init() and EVP_PKEY_decapsulate() were added in OpenSSL 3.0.

The function EVP_PKEY_auth_decapsulate_init() was added in OpenSSL 3.2.

"},{"location":"man3/EVP_PKEY_decapsulate/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2023 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.

"},{"location":"man3/EVP_PKEY_decrypt/","title":"EVP_PKEY_decrypt","text":""},{"location":"man3/EVP_PKEY_decrypt/#name","title":"NAME","text":"

EVP_PKEY_decrypt_init, EVP_PKEY_decrypt_init_ex, EVP_PKEY_decrypt - decrypt using a public key algorithm

"},{"location":"man3/EVP_PKEY_decrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_decrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx,\n                     unsigned char *out, size_t *outlen,\n                     const unsigned char *in, size_t inlen);\n
"},{"location":"man3/EVP_PKEY_decrypt/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_decrypt_init() function initializes a public key algorithm context using key pkey for a decryption operation.

The EVP_PKEY_decrypt_init_ex() function initializes a public key algorithm context using key pkey for a decryption operation and sets the algorithm specific params.

The EVP_PKEY_decrypt() function performs a public key decryption operation using ctx. The data to be decrypted is specified using the in and inlen parameters. If out is NULL then the minimum required size of the output buffer is written to the *outlen parameter.

If out is not NULL then before the call the *outlen parameter must contain the length of the out buffer. If the call is successful the decrypted data is written to out and the amount of the decrypted data written to *outlen, otherwise an error is returned.

"},{"location":"man3/EVP_PKEY_decrypt/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_decrypt_init() algorithm specific control operations can be performed to set any appropriate parameters for the operation. These operations can be included in the EVP_PKEY_decrypt_init_ex() call.

The function EVP_PKEY_decrypt() can be called more than once on the same context if several operations are performed using the same parameters.

"},{"location":"man3/EVP_PKEY_decrypt/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_decrypt_init(), EVP_PKEY_decrypt_init_ex() and EVP_PKEY_decrypt() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_decrypt/#warnings","title":"WARNINGS","text":"

In OpenSSL versions before 3.2.0, when used in PKCS#1 v1.5 padding, both the return value from the EVP_PKEY_decrypt() and the outlen provided information useful in mounting a Bleichenbacher attack against the used private key. They had to be processed in a side-channel free way.

Since version 3.2.0, the EVP_PKEY_decrypt() method when used with PKCS#1 v1.5 padding as implemented in the default provider implements the implicit rejection mechanism (see OSSL_PKEY_PARAM_IMPLICIT_REJECTION in provider-asym_cipher(7)). That means it doesn't return an error when it detects an error in padding, instead it returns a pseudo-randomly generated message, removing the need of side-channel secure code from applications using OpenSSL. If OpenSSL is configured to use a provider that doesn't implement implicit rejection, the code still needs to handle the returned values using side-channel free code. Side-channel free handling of the error stack can be performed using either a pair of unconditional ERR_set_mark(3) and ERR_pop_to_mark(3) calls or by using the ERR_clear_error(3) call.

"},{"location":"man3/EVP_PKEY_decrypt/#examples","title":"EXAMPLES","text":"

Decrypt data using OAEP (for RSA keys):

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nENGINE *eng;\nunsigned char *out, *in;\nsize_t outlen, inlen;\nEVP_PKEY *key;\n\n/*\n * NB: assumes key, eng, in, inlen are already set up\n * and that key is an RSA private key\n */\nctx = EVP_PKEY_CTX_new(key, eng);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_decrypt_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0)\n    /* Error */\n\nout = OPENSSL_malloc(outlen);\n\nif (!out)\n    /* malloc failure */\n\nif (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0)\n    /* Error */\n\n/* Decrypted data is outlen bytes written to buffer out */\n
"},{"location":"man3/EVP_PKEY_decrypt/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_decrypt/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 1.0.0.

"},{"location":"man3/EVP_PKEY_decrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_PKEY_derive/","title":"EVP_PKEY_derive","text":""},{"location":"man3/EVP_PKEY_derive/#name","title":"NAME","text":"

EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret

"},{"location":"man3/EVP_PKEY_derive/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,\n                                int validate_peer);\nint EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);\nint EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);\n
"},{"location":"man3/EVP_PKEY_derive/#description","title":"DESCRIPTION","text":"

EVP_PKEY_derive_init() initializes a public key algorithm context ctx for shared secret derivation using the algorithm given when the context was created using EVP_PKEY_CTX_new(3) or variants thereof. The algorithm is used to fetch a EVP_KEYEXCH method implicitly, see \"Implicit fetch\" in provider(7) for more information about implicit fetches.

EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but additionally sets the passed parameters params on the context before returning.

EVP_PKEY_derive_set_peer_ex() sets the peer key: this will normally be a public key. The validate_peer will validate the public key if this value is non zero.

EVP_PKEY_derive_set_peer() is similar to EVP_PKEY_derive_set_peer_ex() with validate_peer set to 1.

EVP_PKEY_derive() derives a shared secret using ctx. If key is NULL then the maximum size of the output buffer is written to the keylen parameter. If key is not NULL then before the call the keylen parameter should contain the length of the key buffer, if the call is successful the shared secret is written to key and the amount of data written to keylen.

"},{"location":"man3/EVP_PKEY_derive/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_derive_init(), algorithm specific control operations can be performed to set any appropriate parameters for the operation.

The function EVP_PKEY_derive() can be called more than once on the same context if several operations are performed using the same parameters.

"},{"location":"man3/EVP_PKEY_derive/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_derive/#examples","title":"EXAMPLES","text":"

Derive shared secret (for example DH or EC keys):

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nENGINE *eng;\nunsigned char *skey;\nsize_t skeylen;\nEVP_PKEY *pkey, *peerkey;\n/* NB: assumes pkey, eng, peerkey have been already set up */\n\nctx = EVP_PKEY_CTX_new(pkey, eng);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_derive_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)\n    /* Error */\n\nskey = OPENSSL_malloc(skeylen);\n\nif (!skey)\n    /* malloc failure */\n\nif (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)\n    /* Error */\n\n/* Shared secret is skey bytes written to buffer skey */\n
"},{"location":"man3/EVP_PKEY_derive/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_KEYEXCH_fetch(3)

"},{"location":"man3/EVP_PKEY_derive/#history","title":"HISTORY","text":"

The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and EVP_PKEY_derive() functions were originally added in OpenSSL 1.0.0.

The EVP_PKEY_derive_init_ex() and EVP_PKEY_derive_set_peer_ex() functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_derive/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2022 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.

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/","title":"EVP_PKEY_digestsign_supports_digest","text":""},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#name","title":"NAME","text":"

EVP_PKEY_digestsign_supports_digest - indicate support for signature digest

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\nint EVP_PKEY_digestsign_supports_digest(EVP_PKEY *pkey, OSSL_LIB_CTX *libctx,\n                                        const char *name, const char *propq);\n
"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_digestsign_supports_digest() function queries whether the message digest name is supported for public key signature operations associated with key pkey. The query is done within an optional library context libctx and with an optional property query propq.

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#return-values","title":"RETURN VALUES","text":"

The EVP_PKEY_digestsign_supports_digest() function returns 1 if the message digest algorithm identified by name can be used for public key signature operations associated with key pkey and 0 if it cannot be used. It returns a negative value for failure.

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#see-also","title":"SEE ALSO","text":"

EVP_DigestSignInit_ex(3),

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#history","title":"HISTORY","text":"

The EVP_PKEY_digestsign_supports_digest() function was added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_digestsign_supports_digest/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_PKEY_encapsulate/","title":"EVP_PKEY_encapsulate","text":""},{"location":"man3/EVP_PKEY_encapsulate/#name","title":"NAME","text":"

EVP_PKEY_encapsulate_init, EVP_PKEY_auth_encapsulate_init, EVP_PKEY_encapsulate - Key encapsulation using a KEM algorithm with a public key

"},{"location":"man3/EVP_PKEY_encapsulate/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_auth_encapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpriv,\n                                  const OSSL_PARAM params[]);\nint EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx,\n                         unsigned char *wrappedkey, size_t *wrappedkeylen,\n                         unsigned char *genkey, size_t *genkeylen);\n
"},{"location":"man3/EVP_PKEY_encapsulate/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_encapsulate_init() function initializes a public key algorithm context ctx for an encapsulation operation and then sets the params on the context in the same way as calling EVP_PKEY_CTX_set_params(3). Note that ctx is usually is produced using EVP_PKEY_CTX_new_from_pkey(3), specifying the public key to use.

The EVP_PKEY_auth_encapsulate_init() function is similar to EVP_PKEY_encapsulate_init() but also passes an authpriv authentication private key that is used during encapsulation.

The EVP_PKEY_encapsulate() function performs a public key encapsulation operation using ctx. The symmetric secret generated in genkey can be used as key material. The ciphertext in wrappedkey is its encapsulated form, which can be sent to another party, who can use EVP_PKEY_decapsulate(3) to retrieve it using their private key. If wrappedkey is NULL then the maximum size of the output buffer is written to the *wrappedkeylen parameter unless wrappedkeylen is NULL and the maximum size of the generated key buffer is written to *genkeylen unless genkeylen is NULL. If wrappedkey is not NULL and the call is successful then the internally generated key is written to genkey and its size is written to *genkeylen. The encapsulated version of the generated key is written to wrappedkey and its size is written to *wrappedkeylen. Note that if wrappedlen is not NULL, then the value it points to must initially hold the size of the unwrapped buffer so that its size can be validated by the call, ensuring it is large enough to hold the result written to wrapped.

"},{"location":"man3/EVP_PKEY_encapsulate/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_encapsulate_init() algorithm-specific parameters for the operation may be set or modified using EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_PKEY_encapsulate/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_encapsulate_init(), EVP_PKEY_auth_encapsulate_init() and EVP_PKEY_encapsulate() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_encapsulate/#examples","title":"EXAMPLES","text":"

Encapsulate an RSASVE key (for RSA keys).

#include <openssl/evp.h>\n\n/*\n * NB: assumes rsa_pub_key is an public key of another party.\n */\n\nEVP_PKEY_CTX *ctx = NULL;\nsize_t secretlen = 0, outlen = 0;\nunsigned char *out = NULL, *secret = NULL;\n\nctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL);\nif (ctx == NULL)\n    /* Error */\nif (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0)\n    /* Error */\n\n/* Set the mode - only 'RSASVE' is currently supported */\n if (EVP_PKEY_CTX_set_kem_op(ctx, \"RSASVE\") <= 0)\n    /* Error */\n/* Determine buffer length */\nif (EVP_PKEY_encapsulate(ctx, NULL, &outlen, NULL, &secretlen) <= 0)\n    /* Error */\n\nout = OPENSSL_malloc(outlen);\nsecret = OPENSSL_malloc(secretlen);\nif (out == NULL || secret == NULL)\n    /* malloc failure */\n\n/*\n * The generated 'secret' can be used as key material.\n * The encapsulated 'out' can be sent to another party who can\n * decapsulate it using their private key to retrieve the 'secret'.\n */\nif (EVP_PKEY_encapsulate(ctx, out, &outlen, secret, &secretlen) <= 0)\n    /* Error */\n
"},{"location":"man3/EVP_PKEY_encapsulate/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new_from_pkey(3), EVP_PKEY_decapsulate(3), EVP_KEM-RSA(7), EVP_KEM-X25519(7), EVP_KEM-EC(7)

"},{"location":"man3/EVP_PKEY_encapsulate/#history","title":"HISTORY","text":"

These functions EVP_PKEY_encapsulate_init() and EVP_PKEY_encapsulate() were added in OpenSSL 3.0. The function EVP_PKEY_auth_encapsulate_init() was added in OpenSSL 3.2.

"},{"location":"man3/EVP_PKEY_encapsulate/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2023 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.

"},{"location":"man3/EVP_PKEY_encrypt/","title":"EVP_PKEY_encrypt","text":""},{"location":"man3/EVP_PKEY_encrypt/#name","title":"NAME","text":"

EVP_PKEY_encrypt_init_ex, EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm

"},{"location":"man3/EVP_PKEY_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_encrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx,\n                     unsigned char *out, size_t *outlen,\n                     const unsigned char *in, size_t inlen);\n
"},{"location":"man3/EVP_PKEY_encrypt/#description","title":"DESCRIPTION","text":"

The EVP_PKEY_encrypt_init() function initializes a public key algorithm context using key pkey for an encryption operation.

The EVP_PKEY_encrypt_init_ex() function initializes a public key algorithm context using key pkey for an encryption operation and sets the algorithm specific params.

The EVP_PKEY_encrypt() function performs a public key encryption operation using ctx. The data to be encrypted is specified using the in and inlen parameters. If out is NULL then the maximum size of the output buffer is written to the outlen parameter. If out is not NULL then before the call the outlen parameter should contain the length of the out buffer, if the call is successful the encrypted data is written to out and the amount of data written to outlen.

"},{"location":"man3/EVP_PKEY_encrypt/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_encrypt_init() algorithm specific control operations can be performed to set any appropriate parameters for the operation. These operations can be included in the EVP_PKEY_encrypt_init_ex() call.

The function EVP_PKEY_encrypt() can be called more than once on the same context if several operations are performed using the same parameters.

"},{"location":"man3/EVP_PKEY_encrypt/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_encrypt_init(), EVP_PKEY_encrypt_init_ex() and EVP_PKEY_encrypt() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_encrypt/#examples","title":"EXAMPLES","text":"

Encrypt data using OAEP (for RSA keys). See also PEM_read_PUBKEY(3) or d2i_X509(3) for means to load a public key. You may also simply set 'eng = NULL;' to start with the default OpenSSL RSA implementation:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n#include <openssl/engine.h>\n\nEVP_PKEY_CTX *ctx;\nENGINE *eng;\nunsigned char *out, *in;\nsize_t outlen, inlen;\nEVP_PKEY *key;\n\n/*\n * NB: assumes eng, key, in, inlen are already set up,\n * and that key is an RSA public key\n */\nctx = EVP_PKEY_CTX_new(key, eng);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_encrypt_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0)\n    /* Error */\n\nout = OPENSSL_malloc(outlen);\n\nif (!out)\n    /* malloc failure */\n\nif (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)\n    /* Error */\n\n/* Encrypted data is outlen bytes written to buffer out */\n
"},{"location":"man3/EVP_PKEY_encrypt/#see-also","title":"SEE ALSO","text":"

d2i_X509(3), ENGINE_by_id(3), EVP_PKEY_CTX_new(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_encrypt/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 1.0.0.

"},{"location":"man3/EVP_PKEY_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man3/EVP_PKEY_fromdata/","title":"EVP_PKEY_fromdata","text":""},{"location":"man3/EVP_PKEY_fromdata/#name","title":"NAME","text":"

EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable - functions to create keys and key parameters from user data

"},{"location":"man3/EVP_PKEY_fromdata/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection,\n                      OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection);\n
"},{"location":"man3/EVP_PKEY_fromdata/#description","title":"DESCRIPTION","text":"

The functions described here are used to create new keys from user provided key data, such as n, e and d for a minimal RSA keypair.

These functions use an EVP_PKEY_CTX context, which should primarily be created with EVP_PKEY_CTX_new_from_name(3) or EVP_PKEY_CTX_new_id(3).

The exact key data that the user can pass depends on the key type. These are passed as an OSSL_PARAM(3) array.

EVP_PKEY_fromdata_init() initializes a public key algorithm context for creating a key or key parameters from user data.

EVP_PKEY_fromdata() creates the structure to store a key or key parameters, given data from params, selection and a context that's been initialized with EVP_PKEY_fromdata_init(). The result is written to *ppkey. selection is described in \"Selections\". The parameters that can be used for various types of key are as described by the diverse \"Common parameters\" sections of the EVP_PKEY-RSA(7), EVP_PKEY-DSA(7), EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-ED448(7), EVP_PKEY-X25519(7), EVP_PKEY-X448(7), and EVP_PKEY-ED25519(7) pages.

EVP_PKEY_fromdata_settable() gets a constant OSSL_PARAM(3) array that describes the settable parameters that can be used with EVP_PKEY_fromdata(). selection is described in \"Selections\".

Parameters in the params array that are not among the settable parameters for the given selection are ignored.

"},{"location":"man3/EVP_PKEY_fromdata/#selections","title":"Selections","text":"

The following constants can be used for selection:

"},{"location":"man3/EVP_PKEY_fromdata/#notes","title":"NOTES","text":"

These functions only work with key management methods coming from a provider. This is the mirror function to EVP_PKEY_todata(3).

"},{"location":"man3/EVP_PKEY_fromdata/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_fromdata/#examples","title":"EXAMPLES","text":"

These examples are very terse for the sake of staying on topic, which is the EVP_PKEY_fromdata() set of functions. In real applications, BIGNUMs would be handled and converted to byte arrays with BN_bn2nativepad(), but that's off topic here.

"},{"location":"man3/EVP_PKEY_fromdata/#creating-an-rsa-keypair-using-raw-key-data","title":"Creating an RSA keypair using raw key data","text":"
#include <openssl/evp.h>\n\n/*\n * These are extremely small to make this example simple.  A real\n * and secure application will not use such small numbers.  A real\n * and secure application is expected to use BIGNUMs, and to build\n * this array dynamically.\n */\nunsigned long rsa_n = 0xbc747fc5;\nunsigned long rsa_e = 0x10001;\nunsigned long rsa_d = 0x7b133399;\nOSSL_PARAM params[] = {\n    OSSL_PARAM_ulong(\"n\", &rsa_n),\n    OSSL_PARAM_ulong(\"e\", &rsa_e),\n    OSSL_PARAM_ulong(\"d\", &rsa_d),\n    OSSL_PARAM_END\n};\n\nint main()\n{\n    EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, \"RSA\", NULL);\n    EVP_PKEY *pkey = NULL;\n\n    if (ctx == NULL\n        || EVP_PKEY_fromdata_init(ctx) <= 0\n        || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)\n        exit(1);\n\n    /* Do what you want with |pkey| */\n}\n
"},{"location":"man3/EVP_PKEY_fromdata/#creating-an-ecc-keypair-using-raw-key-data","title":"Creating an ECC keypair using raw key data","text":"
#include <openssl/evp.h>\n#include <openssl/param_build.h>\n#include <openssl/ec.h>\n\n/*\n * Fixed data to represent the private and public key.\n */\nconst unsigned char priv_data[] = {\n    0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,\n    0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,\n    0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,\n    0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d\n};\n/* UNCOMPRESSED FORMAT */\nconst unsigned char pub_data[] = {\n    POINT_CONVERSION_UNCOMPRESSED,\n    0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,\n    0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,\n    0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,\n    0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,\n    0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,\n    0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,\n    0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,\n    0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47\n};\n\nint main()\n{\n    EVP_PKEY_CTX *ctx;\n    EVP_PKEY *pkey = NULL;\n    BIGNUM *priv;\n    OSSL_PARAM_BLD *param_bld;\n    OSSL_PARAM *params = NULL;\n    int exitcode = 0;\n\n    priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);\n\n    param_bld = OSSL_PARAM_BLD_new();\n    if (priv != NULL && param_bld != NULL\n        && OSSL_PARAM_BLD_push_utf8_string(param_bld, \"group\",\n                                           \"prime256v1\", 0)\n        && OSSL_PARAM_BLD_push_BN(param_bld, \"priv\", priv)\n        && OSSL_PARAM_BLD_push_octet_string(param_bld, \"pub\",\n                                            pub_data, sizeof(pub_data)))\n        params = OSSL_PARAM_BLD_to_param(param_bld);\n\n    ctx = EVP_PKEY_CTX_new_from_name(NULL, \"EC\", NULL);\n    if (ctx == NULL\n        || params == NULL\n        || EVP_PKEY_fromdata_init(ctx) <= 0\n        || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {\n        exitcode = 1;\n    } else {\n        /* Do what you want with |pkey| */\n    }\n\n    EVP_PKEY_free(pkey);\n    EVP_PKEY_CTX_free(ctx);\n    OSSL_PARAM_free(params);\n    OSSL_PARAM_BLD_free(param_bld);\n    BN_free(priv);\n\n    exit(exitcode);\n}\n
"},{"location":"man3/EVP_PKEY_fromdata/#finding-out-params-for-an-unknown-key-type","title":"Finding out params for an unknown key type","text":"
#include <openssl/evp.h>\n#include <openssl/core.h>\n\n/* Program expects a key type as first argument */\nint main(int argc, char *argv[])\n{\n    EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);\n    const OSSL_PARAM *settable_params = NULL;\n\n    if (ctx == NULL)\n       exit(1);\n   settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);\n   if (settable_params == NULL)\n        exit(1);\n\n    for (; settable_params->key != NULL; settable_params++) {\n        const char *datatype = NULL;\n\n        switch (settable_params->data_type) {\n        case OSSL_PARAM_INTEGER:\n            datatype = \"integer\";\n            break;\n        case OSSL_PARAM_UNSIGNED_INTEGER:\n            datatype = \"unsigned integer\";\n            break;\n        case OSSL_PARAM_UTF8_STRING:\n            datatype = \"printable string (utf-8 encoding expected)\";\n            break;\n        case OSSL_PARAM_UTF8_PTR:\n            datatype = \"printable string pointer (utf-8 encoding expected)\";\n            break;\n        case OSSL_PARAM_OCTET_STRING:\n            datatype = \"octet string\";\n            break;\n        case OSSL_PARAM_OCTET_PTR:\n            datatype = \"octet string pointer\";\n            break;\n        }\n        printf(\"%s : %s \", settable_params->key, datatype);\n        if (settable_params->data_size == 0)\n            printf(\"(unlimited size)\\n\");\n        else\n            printf(\"(maximum size %zu)\\n\", settable_params->data_size);\n    }\n}\n

The descriptor OSSL_PARAM(3) returned by EVP_PKEY_fromdata_settable() may also be used programmatically, for example with OSSL_PARAM_allocate_from_text(3).

"},{"location":"man3/EVP_PKEY_fromdata/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), provider(7), EVP_PKEY_gettable_params(3), OSSL_PARAM(3), EVP_PKEY_todata(3), EVP_PKEY-RSA(7), EVP_PKEY-DSA(7), EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-ED448(7), EVP_PKEY-X25519(7), EVP_PKEY-X448(7), EVP_PKEY-ED25519(7)

"},{"location":"man3/EVP_PKEY_fromdata/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_fromdata/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2021 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.

"},{"location":"man3/EVP_PKEY_get_attr/","title":"EVP_PKEY_get_attr","text":""},{"location":"man3/EVP_PKEY_get_attr/#name","title":"NAME","text":"

EVP_PKEY_get_attr, EVP_PKEY_get_attr_count, EVP_PKEY_get_attr_by_NID, EVP_PKEY_get_attr_by_OBJ, EVP_PKEY_delete_attr, EVP_PKEY_add1_attr, EVP_PKEY_add1_attr_by_OBJ, EVP_PKEY_add1_attr_by_NID, EVP_PKEY_add1_attr_by_txt - EVP_PKEY X509_ATTRIBUTE functions

"},{"location":"man3/EVP_PKEY_get_attr/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nint EVP_PKEY_get_attr_count(const EVP_PKEY *key);\nint EVP_PKEY_get_attr_by_NID(const EVP_PKEY *key, int nid, int lastpos);\nint EVP_PKEY_get_attr_by_OBJ(const EVP_PKEY *key, const ASN1_OBJECT *obj,\n                             int lastpos);\nX509_ATTRIBUTE *EVP_PKEY_get_attr(const EVP_PKEY *key, int loc);\nX509_ATTRIBUTE *EVP_PKEY_delete_attr(EVP_PKEY *key, int loc);\nint EVP_PKEY_add1_attr(EVP_PKEY *key, X509_ATTRIBUTE *attr);\nint EVP_PKEY_add1_attr_by_OBJ(EVP_PKEY *key,\n                              const ASN1_OBJECT *obj, int type,\n                              const unsigned char *bytes, int len);\nint EVP_PKEY_add1_attr_by_NID(EVP_PKEY *key,\n                              int nid, int type,\n                              const unsigned char *bytes, int len);\nint EVP_PKEY_add1_attr_by_txt(EVP_PKEY *key,\n                              const char *attrname, int type,\n                              const unsigned char *bytes, int len);\n
"},{"location":"man3/EVP_PKEY_get_attr/#description","title":"DESCRIPTION","text":"

These functions are used by PKCS12.

EVP_PKEY_get_attr_by_OBJ() finds the location of the first matching object obj in the key attribute list. The search starts at the position after lastpos. If the returned value is positive then it can be used on the next call to EVP_PKEY_get_attr_by_OBJ() as the value of lastpos in order to iterate through the remaining attributes. lastpos can be set to any negative value on the first call, in order to start searching from the start of the attribute list.

EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

EVP_PKEY_get_attr() returns the X509_ATTRIBUTE object at index loc in the key attribute list. loc should be in the range from 0 to EVP_PKEY_get_attr_count() - 1.

EVP_PKEY_delete_attr() removes the X509_ATTRIBUTE object at index loc in the key attribute list.

EVP_PKEY_add1_attr() pushes a copy of the passed in X509_ATTRIBUTE object to the key attribute list. A new key attribute list is created if required. An error occurs if either attr is NULL, or the attribute already exists.

EVP_PKEY_add1_attr_by_OBJ() creates a new X509_ATTRIBUTE using X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new obj with type type and data bytes of length len and then pushes it to the key object's attribute list. If obj already exists in the attribute list then an error occurs.

EVP_PKEY_add1_attr_by_NID() is similar to EVP_PKEY_add1_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

EVP_PKEY_add1_attr_by_txt() is similar to EVP_PKEY_add1_attr_by_OBJ() except that it passes a name attrname associated with the object. See <openssl/obj_mac.h> for a list of SN_* names.

"},{"location":"man3/EVP_PKEY_get_attr/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_get_attr_count() returns the number of attributes in the key object attribute list or -1 if the attribute list is NULL.

EVP_PKEY_get_attr_by_OBJ() returns -1 if either the list is empty OR the object is not found, otherwise it returns the location of the object in the list.

EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ(), except that it returns -2 if the nid is not known by OpenSSL.

EVP_PKEY_get_attr() returns either a X509_ATTRIBUTE or NULL if there is a error.

EVP_PKEY_delete_attr() returns either the removed X509_ATTRIBUTE or NULL if there is a error.

EVP_PKEY_add1_attr(), EVP_PKEY_add1_attr_by_OBJ(), EVP_PKEY_add1_attr_by_NID() and EVP_PKEY_add1_attr_by_txt() return 1 on success or 0 otherwise.

"},{"location":"man3/EVP_PKEY_get_attr/#notes","title":"NOTES","text":"

A EVP_PKEY object's attribute list is initially NULL. All the above functions listed will return an error unless EVP_PKEY_add1_attr() is called. All functions listed assume that the key is not NULL.

"},{"location":"man3/EVP_PKEY_get_attr/#see-also","title":"SEE ALSO","text":"

X509_ATTRIBUTE(3)

"},{"location":"man3/EVP_PKEY_get_attr/#copyright","title":"COPYRIGHT","text":"

Copyright 2023-2024 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.

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/","title":"EVP_PKEY_get_default_digest_nid","text":""},{"location":"man3/EVP_PKEY_get_default_digest_nid/#name","title":"NAME","text":"

EVP_PKEY_get_default_digest_nid, EVP_PKEY_get_default_digest_name - get default signature digest

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_get_default_digest_name(EVP_PKEY *pkey,\n                                     char *mdname, size_t mdname_sz);\nint EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid);\n
"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#description","title":"DESCRIPTION","text":"

EVP_PKEY_get_default_digest_name() fills in the default message digest name for the public key signature operations associated with key pkey into mdname, up to at most mdname_sz bytes including the ending NUL byte. The name could be \"UNDEF\", signifying that a digest must (for return value 2) or may (for return value 1) be left unspecified.

EVP_PKEY_get_default_digest_nid() sets pnid to the default message digest NID for the public key signature operations associated with key pkey. Note that some signature algorithms (i.e. Ed25519 and Ed448) do not use a digest during signing. In this case pnid will be set to NID_undef. This function is only reliable for legacy keys, which are keys with a EVP_PKEY_ASN1_METHOD; these keys have typically been loaded from engines, or created with EVP_PKEY_assign_RSA(3) or similar.

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#notes","title":"NOTES","text":"

For all current standard OpenSSL public key algorithms SHA256 is returned.

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_get_default_digest_name() and EVP_PKEY_get_default_digest_nid() both return 1 if the message digest is advisory (that is other digests can be used) and 2 if it is mandatory (other digests can not be used). They return 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_sign(3), EVP_PKEY_digestsign_supports_digest(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3),

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#history","title":"HISTORY","text":"

This function was added in OpenSSL 1.0.0.

"},{"location":"man3/EVP_PKEY_get_default_digest_nid/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2023 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.

"},{"location":"man3/EVP_PKEY_get_field_type/","title":"EVP_PKEY_get_field_type","text":""},{"location":"man3/EVP_PKEY_get_field_type/#name","title":"NAME","text":"

EVP_PKEY_get_field_type, EVP_PKEY_get_ec_point_conv_form - get field type or point conversion form of a key

"},{"location":"man3/EVP_PKEY_get_field_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_get_field_type(const EVP_PKEY *pkey);\nint EVP_PKEY_get_ec_point_conv_form(const EVP_PKEY *pkey);\n
"},{"location":"man3/EVP_PKEY_get_field_type/#description","title":"DESCRIPTION","text":"

EVP_PKEY_get_field_type() returns the field type NID of the pkey, if pkey's key type supports it. The types currently supported by the built-in OpenSSL providers are either NID_X9_62_prime_field for prime curves or NID_X9_62_characteristic_two_field for binary curves; these values are defined in the <openssl/obj_mac.h> header file.

EVP_PKEY_get_ec_point_conv_form() returns the point conversion format of the pkey, if pkey's key type supports it.

"},{"location":"man3/EVP_PKEY_get_field_type/#notes","title":"NOTES","text":"

Among the standard OpenSSL key types, this is only supported for EC and SM2 keys. Other providers may support this for additional key types.

"},{"location":"man3/EVP_PKEY_get_field_type/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_get_field_type() returns the field type NID or 0 on error.

EVP_PKEY_get_ec_point_conv_form() returns the point conversion format number (see EC_GROUP_copy(3)) or 0 on error.

"},{"location":"man3/EVP_PKEY_get_field_type/#see-also","title":"SEE ALSO","text":"

EC_GROUP_copy(3)

"},{"location":"man3/EVP_PKEY_get_field_type/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_get_field_type/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/EVP_PKEY_get_group_name/","title":"EVP_PKEY_get_group_name","text":""},{"location":"man3/EVP_PKEY_get_group_name/#name","title":"NAME","text":"

EVP_PKEY_get_group_name - get group name of a key

"},{"location":"man3/EVP_PKEY_get_group_name/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_get_group_name(EVP_PKEY *pkey, char *gname, size_t gname_sz,\n                            size_t *gname_len);\n
"},{"location":"man3/EVP_PKEY_get_group_name/#description","title":"DESCRIPTION","text":"

EVP_PKEY_get_group_name() fills in the group name of the pkey into gname, up to at most gname_sz bytes including the ending NUL byte and assigns *gname_len the actual length of the name not including the NUL byte, if pkey's key type supports it. gname as well as gname_len may individually be NULL, and won't be filled in or assigned in that case.

"},{"location":"man3/EVP_PKEY_get_group_name/#notes","title":"NOTES","text":"

Among the standard OpenSSL key types, this is only supported for DH, EC and SM2 keys. Other providers may support this for additional key types.

"},{"location":"man3/EVP_PKEY_get_group_name/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_get_group_name() returns 1 if the group name could be filled in, otherwise 0.

"},{"location":"man3/EVP_PKEY_get_group_name/#history","title":"HISTORY","text":"

This function was added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_get_group_name/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_get_size/","title":"EVP_PKEY_get_size","text":""},{"location":"man3/EVP_PKEY_get_size/#name","title":"NAME","text":"

EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits, EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size - EVP_PKEY information functions

"},{"location":"man3/EVP_PKEY_get_size/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_get_size(const EVP_PKEY *pkey);\nint EVP_PKEY_get_bits(const EVP_PKEY *pkey);\nint EVP_PKEY_get_security_bits(const EVP_PKEY *pkey);\n\n#define EVP_PKEY_bits EVP_PKEY_get_bits\n#define EVP_PKEY_security_bits EVP_PKEY_get_security_bits\n#define EVP_PKEY_size EVP_PKEY_get_size\n
"},{"location":"man3/EVP_PKEY_get_size/#description","title":"DESCRIPTION","text":"

EVP_PKEY_get_size() returns the maximum suitable size for the output buffers for almost all operations that can be done with pkey. This corresponds to the provider parameter OSSL_PKEY_PARAM_MAX_SIZE. The primary documented use is with EVP_SignFinal(3) and EVP_SealInit(3), but it isn't limited there. The returned size is also large enough for the output buffer of EVP_PKEY_sign(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_derive(3).

It must be stressed that, unless the documentation for the operation that's being performed says otherwise, the size returned by EVP_PKEY_get_size() is only preliminary and not exact, so the final contents of the target buffer may be smaller. It is therefore crucial to take note of the size given back by the function that performs the operation, such as EVP_PKEY_sign(3) (the siglen argument will receive that length), to avoid bugs.

EVP_PKEY_get_bits() returns the cryptographic length of the cryptosystem to which the key in pkey belongs, in bits. Note that the definition of cryptographic length is specific to the key cryptosystem. This length corresponds to the provider parameter OSSL_PKEY_PARAM_BITS.

EVP_PKEY_get_security_bits() returns the number of security bits of the given pkey, bits of security is defined in NIST SP800-57. This corresponds to the provider parameter OSSL_PKEY_PARAM_SECURITY_BITS.

"},{"location":"man3/EVP_PKEY_get_size/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_get_size(), EVP_PKEY_get_bits() and EVP_PKEY_get_security_bits() return a positive number, or 0 if this size isn't available.

"},{"location":"man3/EVP_PKEY_get_size/#notes","title":"NOTES","text":"

Most functions that have an output buffer and are mentioned with EVP_PKEY_get_size() have a functionality where you can pass NULL for the buffer and still pass a pointer to an integer and get the exact size that this function call delivers in the context that it's called in. This allows those functions to be called twice, once to find out the exact buffer size, then allocate the buffer in between, and call that function again actually output the data. For those functions, it isn't strictly necessary to call EVP_PKEY_get_size() to find out the buffer size, but may be useful in cases where it's desirable to know the upper limit in advance.

It should also be especially noted that EVP_PKEY_get_size() shouldn't be used to get the output size for EVP_DigestSignFinal(), according to \"NOTES\" in EVP_DigestSignFinal(3).

"},{"location":"man3/EVP_PKEY_get_size/#see-also","title":"SEE ALSO","text":"

provider-keymgmt(7), EVP_SignFinal(3), EVP_SealInit(3), EVP_PKEY_sign(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_get_size/#history","title":"HISTORY","text":"

The EVP_PKEY_bits(), EVP_PKEY_security_bits(), and EVP_PKEY_size() functions were renamed to include get in their names in OpenSSL 3.0, respectively. The old names are kept as non-deprecated alias macros.

"},{"location":"man3/EVP_PKEY_get_size/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_gettable_params/","title":"EVP_PKEY_gettable_params","text":""},{"location":"man3/EVP_PKEY_gettable_params/#name","title":"NAME","text":"

EVP_PKEY_gettable_params, EVP_PKEY_get_params, EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param, EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param, EVP_PKEY_get_octet_string_param - retrieve key parameters from a key

"},{"location":"man3/EVP_PKEY_gettable_params/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);\nint EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);\nint EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,\n                           int *out);\nint EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,\n                              size_t *out);\nint EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,\n                          BIGNUM **bn);\nint EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,\n                                   char *str, size_t max_buf_sz,\n                                   size_t *out_len);\nint EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,\n                                    unsigned char *buf, size_t max_buf_sz,\n                                    size_t *out_len);\n
"},{"location":"man3/EVP_PKEY_gettable_params/#description","title":"DESCRIPTION","text":"

See OSSL_PARAM(3) for information about parameters.

EVP_PKEY_get_params() retrieves parameters from the key pkey, according to the contents of params.

EVP_PKEY_gettable_params() returns a constant list of params indicating the names and types of key parameters that can be retrieved.

An OSSL_PARAM(3) of type OSSL_PARAM_INTEGER or OSSL_PARAM_UNSIGNED_INTEGER is of arbitrary length. Such a parameter can be obtained using any of the functions EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param() or EVP_PKEY_get_bn_param(). Attempting to obtain an integer value that does not fit into a native C int type will cause EVP_PKEY_get_int_param() to fail. Similarly attempting to obtain an integer value that is negative or does not fit into a native C size_t type using EVP_PKEY_get_size_t_param() will also fail.

EVP_PKEY_get_int_param() retrieves a key pkey integer value *out associated with a name of key_name if it fits into int type. For parameters that do not fit into int use EVP_PKEY_get_bn_param().

EVP_PKEY_get_size_t_param() retrieves a key pkey size_t value *out associated with a name of key_name if it fits into size_t type. For parameters that do not fit into size_t use EVP_PKEY_get_bn_param().

EVP_PKEY_get_bn_param() retrieves a key pkey BIGNUM value **bn associated with a name of key_name. If *bn is NULL then the BIGNUM is allocated by the method.

EVP_PKEY_get_utf8_string_param() get a key pkey UTF8 string value into a buffer str of maximum size max_buf_sz associated with a name of key_name. The maximum size must be large enough to accommodate the string value including a terminating NUL byte, or this function will fail. If out_len is not NULL, *out_len is set to the length of the string not including the terminating NUL byte. The required buffer size not including the terminating NUL byte can be obtained from *out_len by calling the function with str set to NULL.

EVP_PKEY_get_octet_string_param() get a key pkey's octet string value into a buffer buf of maximum size max_buf_sz associated with a name of key_name. If out_len is not NULL, *out_len is set to the length of the contents. The required buffer size can be obtained from *out_len by calling the function with buf set to NULL.

"},{"location":"man3/EVP_PKEY_gettable_params/#notes","title":"NOTES","text":"

These functions only work for EVP_PKEYs that contain a provider side key.

"},{"location":"man3/EVP_PKEY_gettable_params/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_gettable_params() returns NULL on error or if it is not supported.

All other methods return 1 if a value associated with the key's key_name was successfully returned, or 0 if there was an error. An error may be returned by methods EVP_PKEY_get_utf8_string_param() and EVP_PKEY_get_octet_string_param() if max_buf_sz is not big enough to hold the value. If out_len is not NULL, *out_len will be assigned the required buffer size to hold the value.

"},{"location":"man3/EVP_PKEY_gettable_params/#examples","title":"EXAMPLES","text":"
#include <openssl/evp.h>\n\nchar curve_name[64];\nunsigned char pub[256];\nBIGNUM *bn_priv = NULL;\n\n/*\n * NB: assumes 'key' is set up before the next step. In this example the key\n * is an EC key.\n */\n\nif (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,\n                                    curve_name, sizeof(curve_name), &len)) {\n  /* Error */\n}\nif (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,\n                                     pub, sizeof(pub), &len)) {\n    /* Error */\n}\nif (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {\n    /* Error */\n}\n\nBN_clear_free(bn_priv);\n
"},{"location":"man3/EVP_PKEY_gettable_params/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), provider-keymgmt(7), OSSL_PARAM(3)

"},{"location":"man3/EVP_PKEY_gettable_params/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_gettable_params/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2022 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.

"},{"location":"man3/EVP_PKEY_is_a/","title":"EVP_PKEY_is_a","text":""},{"location":"man3/EVP_PKEY_is_a/#name","title":"NAME","text":"

EVP_PKEY_is_a, EVP_PKEY_can_sign, EVP_PKEY_type_names_do_all, EVP_PKEY_get0_type_name, EVP_PKEY_get0_description, EVP_PKEY_get0_provider - key type and capabilities functions

"},{"location":"man3/EVP_PKEY_is_a/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name);\nint EVP_PKEY_can_sign(const EVP_PKEY *pkey);\nint EVP_PKEY_type_names_do_all(const EVP_PKEY *pkey,\n                               void (*fn)(const char *name, void *data),\n                               void *data);\nconst char *EVP_PKEY_get0_type_name(const EVP_PKEY *key);\nconst char *EVP_PKEY_get0_description(const EVP_PKEY *key);\nconst OSSL_PROVIDER *EVP_PKEY_get0_provider(const EVP_PKEY *key);\n
"},{"location":"man3/EVP_PKEY_is_a/#description","title":"DESCRIPTION","text":"

EVP_PKEY_is_a() checks if the key type of pkey is name.

EVP_PKEY_can_sign() checks if the functionality for the key type of pkey supports signing. No other check is done, such as whether pkey contains a private key.

EVP_PKEY_type_names_do_all() traverses all names for pkey's key type, and calls fn with each name and data. For example, an RSA EVP_PKEY may be named both RSA and rsaEncryption. The order of the names depends on the provider implementation that holds the key.

EVP_PKEY_get0_type_name() returns the first key type name that is found for the given pkey. Note that the pkey may have multiple synonyms associated with it. In this case it depends on the provider implementation that holds the key which one will be returned. Ownership of the returned string is retained by the pkey object and should not be freed by the caller.

EVP_PKEY_get0_description() returns a description of the type of EVP_PKEY, meant for display and human consumption. The description is at the discretion of the key type implementation.

EVP_PKEY_get0_provider() returns the provider of the EVP_PKEY's EVP_KEYMGMT(3).

"},{"location":"man3/EVP_PKEY_is_a/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_is_a() returns 1 if pkey has the key type name, otherwise 0.

EVP_PKEY_can_sign() returns 1 if the pkey key type functionality supports signing, otherwise 0.

EVP_PKEY_get0_type_name() returns the name that is found or NULL on error.

EVP_PKEY_get0_description() returns the description if found or NULL if not.

EVP_PKEY_get0_provider() returns the provider if found or NULL if not.

EVP_PKEY_type_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

"},{"location":"man3/EVP_PKEY_is_a/#examples","title":"EXAMPLES","text":""},{"location":"man3/EVP_PKEY_is_a/#evp_pkey_is_a_1","title":"EVP_PKEY_is_a()","text":"

The loaded providers and what key types they support will ultimately determine what name is possible to use with EVP_PKEY_is_a(). We do know that the default provider supports RSA, DH, DSA and EC keys, so we can use this as an crude example:

#include <openssl/evp.h>\n\n...\n    /* |pkey| is an EVP_PKEY* */\n    if (EVP_PKEY_is_a(pkey, \"RSA\")) {\n        BIGNUM *modulus = NULL;\n        if (EVP_PKEY_get_bn_param(pkey, \"n\", &modulus))\n            /* do whatever with the modulus */\n        BN_free(modulus);\n    }\n
"},{"location":"man3/EVP_PKEY_is_a/#evp_pkey_can_sign","title":"EVP_PKEY_can_sign()","text":"
#include <openssl/evp.h>\n\n...\n    /* |pkey| is an EVP_PKEY* */\n    if (!EVP_PKEY_can_sign(pkey)) {\n        fprintf(stderr, \"Not a signing key!\");\n        exit(1);\n    }\n    /* Sign something... */\n
"},{"location":"man3/EVP_PKEY_is_a/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_is_a/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_keygen/","title":"EVP_PKEY_keygen","text":""},{"location":"man3/EVP_PKEY_keygen/#name","title":"NAME","text":"

EVP_PKEY_Q_keygen, EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_generate, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data, EVP_PKEY_gen_cb, EVP_PKEY_paramgen, EVP_PKEY_keygen - key and parameter generation and check functions

"},{"location":"man3/EVP_PKEY_keygen/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_PKEY *EVP_PKEY_Q_keygen(OSSL_LIB_CTX *libctx, const char *propq,\n                            const char *type, ...);\n\nint EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_generate(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);\nint EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);\nint EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);\n\ntypedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);\n\nvoid EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);\nEVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);\n\nint EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);\n\nvoid EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);\nvoid *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);\n
"},{"location":"man3/EVP_PKEY_keygen/#description","title":"DESCRIPTION","text":"

Generating keys is sometimes straight forward, just generate the key's numbers and be done with it. However, there are certain key types that need key parameters, often called domain parameters but not necessarily limited to that, that also need to be generated. In addition to this, the caller may want to set user provided generation parameters that further affect key parameter or key generation, such as the desired key size.

To flexibly allow all that's just been described, key parameter and key generation is divided into an initialization of a key algorithm context, functions to set user provided parameters, and finally the key parameter or key generation function itself.

The key algorithm context must be created using EVP_PKEY_CTX_new(3) or variants thereof, see that manual for details.

EVP_PKEY_keygen_init() initializes a public key algorithm context ctx for a key generation operation.

EVP_PKEY_paramgen_init() is similar to EVP_PKEY_keygen_init() except key parameters are generated.

After initialization, generation parameters may be provided with EVP_PKEY_CTX_ctrl(3) or EVP_PKEY_CTX_set_params(3), or any other function described in those manuals.

EVP_PKEY_generate() performs the generation operation, the resulting key parameters or key are written to *ppkey. If *ppkey is NULL when this function is called, it will be allocated, and should be freed by the caller when no longer useful, using EVP_PKEY_free(3).

EVP_PKEY_paramgen() and EVP_PKEY_keygen() do exactly the same thing as EVP_PKEY_generate(), after checking that the corresponding EVP_PKEY_paramgen_init() or EVP_PKEY_keygen_init() was used to initialize ctx. These are older functions that are kept for backward compatibility. It is safe to use EVP_PKEY_generate() instead.

The function EVP_PKEY_set_cb() sets the key or parameter generation callback to cb. The function EVP_PKEY_CTX_get_cb() returns the key or parameter generation callback.

The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated with the generation operation. If idx is -1 the total number of parameters available is returned. Any non negative value returns the value of that parameter. EVP_PKEY_CTX_gen_keygen_info() with a nonnegative value for idx should only be called within the generation callback.

If the callback returns 0 then the key generation operation is aborted and an error occurs. This might occur during a time consuming operation where a user clicks on a \"cancel\" button.

The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set and retrieve an opaque pointer. This can be used to set some application defined value which can be retrieved in the callback: for example a handle which is used to update a \"progress dialog\".

EVP_PKEY_Q_keygen() abstracts from the explicit use of EVP_PKEY_CTX while providing a 'quick' but limited way of generating a new asymmetric key pair. It provides shorthands for simple and common cases of key generation. As usual, the library context libctx and property query propq can be given for fetching algorithms from providers. If type is RSA, a size_t parameter must be given to specify the size of the RSA key. If type is EC, a string parameter must be given to specify the name of the EC curve. If type is X25519, X448, ED25519, ED448, or SM2 no further parameter is needed. Other key types may be possible if they are supplied by the loaded providers. EVP_PKEY_Q_keygen() may be usable with such key types as long as they do not require further parameters.

"},{"location":"man3/EVP_PKEY_keygen/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

EVP_PKEY_Q_keygen() returns an EVP_PKEY, or NULL on failure.

"},{"location":"man3/EVP_PKEY_keygen/#notes","title":"NOTES","text":"

After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm specific control operations can be performed to set any appropriate parameters for the operation.

The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than once on the same context if several operations are performed using the same parameters.

The meaning of the parameters passed to the callback will depend on the algorithm and the specific implementation of the algorithm. Some might not give any useful information at all during key or parameter generation. Others might not even call the callback.

The operation performed by key or parameter generation depends on the algorithm used. In some cases (e.g. EC with a supplied named curve) the \"generation\" option merely sets the appropriate fields in an EVP_PKEY structure.

In OpenSSL an EVP_PKEY structure containing a private key also contains the public key components and parameters (if any). An OpenSSL private key is equivalent to what some libraries call a \"key pair\". A private key can be used in functions which require the use of a public key or parameters.

"},{"location":"man3/EVP_PKEY_keygen/#examples","title":"EXAMPLES","text":"

Generate a 2048 bit RSA key:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nEVP_PKEY *pkey = NULL;\n\nctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_keygen_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)\n    /* Error */\n\n/* Generate key */\nif (EVP_PKEY_keygen(ctx, &pkey) <= 0)\n    /* Error */\n

Generate a key from a set of parameters:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nENGINE *eng;\nEVP_PKEY *pkey = NULL, *param;\n\n/* Assumed param, eng are set up already */\nctx = EVP_PKEY_CTX_new(param, eng);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_keygen_init(ctx) <= 0)\n    /* Error */\n\n/* Generate key */\nif (EVP_PKEY_keygen(ctx, &pkey) <= 0)\n    /* Error */\n

Example of generation callback for OpenSSL public key implementations:

/* Application data is a BIO to output status to */\n\nEVP_PKEY_CTX_set_app_data(ctx, status_bio);\n\nstatic int genpkey_cb(EVP_PKEY_CTX *ctx)\n{\n    char c = '*';\n    BIO *b = EVP_PKEY_CTX_get_app_data(ctx);\n    int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);\n\n    if (p == 0)\n        c = '.';\n    if (p == 1)\n        c = '+';\n    if (p == 2)\n        c = '*';\n    if (p == 3)\n        c = '\\n';\n    BIO_write(b, &c, 1);\n    (void)BIO_flush(b);\n    return 1;\n}\n
"},{"location":"man3/EVP_PKEY_keygen/#see-also","title":"SEE ALSO","text":"

EVP_RSA_gen(3), EVP_EC_gen(3), EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_keygen/#history","title":"HISTORY","text":"

EVP_PKEY_keygen_init(), int EVP_PKEY_paramgen_init(), EVP_PKEY_keygen(), EVP_PKEY_paramgen(), EVP_PKEY_gen_cb(), EVP_PKEY_CTX_set_cb(), EVP_PKEY_CTX_get_cb(), EVP_PKEY_CTX_get_keygen_info(), EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() were added in OpenSSL 1.0.0.

EVP_PKEY_Q_keygen() and EVP_PKEY_generate() were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_keygen/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man3/EVP_PKEY_meth_get_count/","title":"EVP_PKEY_meth_get_count","text":""},{"location":"man3/EVP_PKEY_meth_get_count/#name","title":"NAME","text":"

EVP_PKEY_meth_get_count, EVP_PKEY_meth_get0, EVP_PKEY_meth_get0_info - enumerate public key methods

"},{"location":"man3/EVP_PKEY_meth_get_count/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

size_t EVP_PKEY_meth_get_count(void);\nconst EVP_PKEY_METHOD *EVP_PKEY_meth_get0(size_t idx);\nvoid EVP_PKEY_meth_get0_info(int *ppkey_id, int *pflags,\n                             const EVP_PKEY_METHOD *meth);\n
"},{"location":"man3/EVP_PKEY_meth_get_count/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the OSSL_PROVIDER APIs.

EVP_PKEY_meth_count() returns a count of the number of public key methods available: it includes standard methods and any methods added by the application.

EVP_PKEY_meth_get0() returns the public key method idx. The value of idx must be between zero and EVP_PKEY_meth_get_count() - 1.

EVP_PKEY_meth_get0_info() returns the public key ID (a NID) and any flags associated with the public key method *meth.

"},{"location":"man3/EVP_PKEY_meth_get_count/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_meth_count() returns the number of available public key methods.

EVP_PKEY_meth_get0() return a public key method or NULL if idx is out of range.

EVP_PKEY_meth_get0_info() does not return a value.

"},{"location":"man3/EVP_PKEY_meth_get_count/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3)

"},{"location":"man3/EVP_PKEY_meth_get_count/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_meth_get_count/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PKEY_meth_new/","title":"EVP_PKEY_meth_new","text":""},{"location":"man3/EVP_PKEY_meth_new/#name","title":"NAME","text":"

EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, EVP_PKEY_meth_add0, EVP_PKEY_METHOD, EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_digestsign, EVP_PKEY_meth_set_digestverify, EVP_PKEY_meth_set_check, EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check, EVP_PKEY_meth_set_digest_custom, EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_digestsign, EVP_PKEY_meth_get_digestverify, EVP_PKEY_meth_get_check, EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check, EVP_PKEY_meth_get_digest_custom, EVP_PKEY_meth_remove - manipulating EVP_PKEY_METHOD structure

"},{"location":"man3/EVP_PKEY_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

typedef struct evp_pkey_method_st EVP_PKEY_METHOD;\n\nEVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);\nvoid EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);\nvoid EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);\nconst EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);\nint EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);\nint EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);\n\nvoid EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,\n                            int (*init) (EVP_PKEY_CTX *ctx));\nvoid EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,\n                            int (*copy) (EVP_PKEY_CTX *dst,\n                                         const EVP_PKEY_CTX *src));\nvoid EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,\n                               void (*cleanup) (EVP_PKEY_CTX *ctx));\nvoid EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,\n                                int (*paramgen_init) (EVP_PKEY_CTX *ctx),\n                                int (*paramgen) (EVP_PKEY_CTX *ctx,\n                                                 EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,\n                              int (*keygen_init) (EVP_PKEY_CTX *ctx),\n                              int (*keygen) (EVP_PKEY_CTX *ctx,\n                                             EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,\n                            int (*sign_init) (EVP_PKEY_CTX *ctx),\n                            int (*sign) (EVP_PKEY_CTX *ctx,\n                                         unsigned char *sig, size_t *siglen,\n                                         const unsigned char *tbs,\n                                         size_t tbslen));\nvoid EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,\n                              int (*verify_init) (EVP_PKEY_CTX *ctx),\n                              int (*verify) (EVP_PKEY_CTX *ctx,\n                                             const unsigned char *sig,\n                                             size_t siglen,\n                                             const unsigned char *tbs,\n                                             size_t tbslen));\nvoid EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,\n                                      int (*verify_recover_init) (EVP_PKEY_CTX\n                                                                  *ctx),\n                                      int (*verify_recover) (EVP_PKEY_CTX\n                                                             *ctx,\n                                                             unsigned char\n                                                             *sig,\n                                                             size_t *siglen,\n                                                             const unsigned\n                                                             char *tbs,\n                                                             size_t tbslen));\nvoid EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,\n                               int (*signctx_init) (EVP_PKEY_CTX *ctx,\n                                                    EVP_MD_CTX *mctx),\n                               int (*signctx) (EVP_PKEY_CTX *ctx,\n                                               unsigned char *sig,\n                                               size_t *siglen,\n                                               EVP_MD_CTX *mctx));\nvoid EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,\n                                 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,\n                                                        EVP_MD_CTX *mctx),\n                                 int (*verifyctx) (EVP_PKEY_CTX *ctx,\n                                                   const unsigned char *sig,\n                                                   int siglen,\n                                                   EVP_MD_CTX *mctx));\nvoid EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,\n                               int (*encrypt_init) (EVP_PKEY_CTX *ctx),\n                               int (*encryptfn) (EVP_PKEY_CTX *ctx,\n                                                 unsigned char *out,\n                                                 size_t *outlen,\n                                                 const unsigned char *in,\n                                                 size_t inlen));\nvoid EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,\n                               int (*decrypt_init) (EVP_PKEY_CTX *ctx),\n                               int (*decrypt) (EVP_PKEY_CTX *ctx,\n                                               unsigned char *out,\n                                               size_t *outlen,\n                                               const unsigned char *in,\n                                               size_t inlen));\nvoid EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,\n                              int (*derive_init) (EVP_PKEY_CTX *ctx),\n                              int (*derive) (EVP_PKEY_CTX *ctx,\n                                             unsigned char *key,\n                                             size_t *keylen));\nvoid EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,\n                            int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,\n                                         void *p2),\n                            int (*ctrl_str) (EVP_PKEY_CTX *ctx,\n                                             const char *type,\n                                             const char *value));\nvoid EVP_PKEY_meth_set_digestsign(EVP_PKEY_METHOD *pmeth,\n                                  int (*digestsign) (EVP_MD_CTX *ctx,\n                                                     unsigned char *sig,\n                                                     size_t *siglen,\n                                                     const unsigned char *tbs,\n                                                     size_t tbslen));\nvoid EVP_PKEY_meth_set_digestverify(EVP_PKEY_METHOD *pmeth,\n                                    int (*digestverify) (EVP_MD_CTX *ctx,\n                                                         const unsigned char *sig,\n                                                         size_t siglen,\n                                                         const unsigned char *tbs,\n                                                         size_t tbslen));\nvoid EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,\n                             int (*check) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,\n                                    int (*check) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth,\n                                   int (*check) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_set_digest_custom(EVP_PKEY_METHOD *pmeth,\n                                    int (*digest_custom) (EVP_PKEY_CTX *ctx,\n                                                          EVP_MD_CTX *mctx));\n\nvoid EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth,\n                            int (**pinit) (EVP_PKEY_CTX *ctx));\nvoid EVP_PKEY_meth_get_copy(const EVP_PKEY_METHOD *pmeth,\n                            int (**pcopy) (EVP_PKEY_CTX *dst,\n                                           EVP_PKEY_CTX *src));\nvoid EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth,\n                               void (**pcleanup) (EVP_PKEY_CTX *ctx));\nvoid EVP_PKEY_meth_get_paramgen(const EVP_PKEY_METHOD *pmeth,\n                                int (**pparamgen_init) (EVP_PKEY_CTX *ctx),\n                                int (**pparamgen) (EVP_PKEY_CTX *ctx,\n                                                   EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_get_keygen(const EVP_PKEY_METHOD *pmeth,\n                              int (**pkeygen_init) (EVP_PKEY_CTX *ctx),\n                              int (**pkeygen) (EVP_PKEY_CTX *ctx,\n                                               EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_get_sign(const EVP_PKEY_METHOD *pmeth,\n                            int (**psign_init) (EVP_PKEY_CTX *ctx),\n                            int (**psign) (EVP_PKEY_CTX *ctx,\n                                           unsigned char *sig, size_t *siglen,\n                                           const unsigned char *tbs,\n                                           size_t tbslen));\nvoid EVP_PKEY_meth_get_verify(const EVP_PKEY_METHOD *pmeth,\n                              int (**pverify_init) (EVP_PKEY_CTX *ctx),\n                              int (**pverify) (EVP_PKEY_CTX *ctx,\n                                               const unsigned char *sig,\n                                               size_t siglen,\n                                               const unsigned char *tbs,\n                                               size_t tbslen));\nvoid EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,\n                                      int (**pverify_recover_init) (EVP_PKEY_CTX\n                                                                    *ctx),\n                                      int (**pverify_recover) (EVP_PKEY_CTX\n                                                               *ctx,\n                                                               unsigned char\n                                                               *sig,\n                                                               size_t *siglen,\n                                                               const unsigned\n                                                               char *tbs,\n                                                               size_t tbslen));\nvoid EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth,\n                               int (**psignctx_init) (EVP_PKEY_CTX *ctx,\n                                                      EVP_MD_CTX *mctx),\n                               int (**psignctx) (EVP_PKEY_CTX *ctx,\n                                                 unsigned char *sig,\n                                                 size_t *siglen,\n                                                 EVP_MD_CTX *mctx));\nvoid EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth,\n                                 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,\n                                                          EVP_MD_CTX *mctx),\n                                 int (**pverifyctx) (EVP_PKEY_CTX *ctx,\n                                                     const unsigned char *sig,\n                                                     int siglen,\n                                                     EVP_MD_CTX *mctx));\nvoid EVP_PKEY_meth_get_encrypt(const EVP_PKEY_METHOD *pmeth,\n                               int (**pencrypt_init) (EVP_PKEY_CTX *ctx),\n                               int (**pencryptfn) (EVP_PKEY_CTX *ctx,\n                                                   unsigned char *out,\n                                                   size_t *outlen,\n                                                   const unsigned char *in,\n                                                   size_t inlen));\nvoid EVP_PKEY_meth_get_decrypt(const EVP_PKEY_METHOD *pmeth,\n                               int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),\n                               int (**pdecrypt) (EVP_PKEY_CTX *ctx,\n                                                 unsigned char *out,\n                                                 size_t *outlen,\n                                                 const unsigned char *in,\n                                                 size_t inlen));\nvoid EVP_PKEY_meth_get_derive(const EVP_PKEY_METHOD *pmeth,\n                              int (**pderive_init) (EVP_PKEY_CTX *ctx),\n                              int (**pderive) (EVP_PKEY_CTX *ctx,\n                                               unsigned char *key,\n                                               size_t *keylen));\nvoid EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth,\n                            int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,\n                                           void *p2),\n                            int (**pctrl_str) (EVP_PKEY_CTX *ctx,\n                                               const char *type,\n                                               const char *value));\nvoid EVP_PKEY_meth_get_digestsign(const EVP_PKEY_METHOD *pmeth,\n                                  int (**digestsign) (EVP_MD_CTX *ctx,\n                                                      unsigned char *sig,\n                                                      size_t *siglen,\n                                                      const unsigned char *tbs,\n                                                      size_t tbslen));\nvoid EVP_PKEY_meth_get_digestverify(const EVP_PKEY_METHOD *pmeth,\n                                    int (**digestverify) (EVP_MD_CTX *ctx,\n                                                          const unsigned char *sig,\n                                                          size_t siglen,\n                                                          const unsigned char *tbs,\n                                                          size_t tbslen));\nvoid EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,\n                             int (**pcheck) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,\n                                    int (**pcheck) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth,\n                                   int (**pcheck) (EVP_PKEY *pkey));\nvoid EVP_PKEY_meth_get_digest_custom(const EVP_PKEY_METHOD *pmeth,\n                                    int (**pdigest_custom) (EVP_PKEY_CTX *ctx,\n                                                            EVP_MD_CTX *mctx));\n
"},{"location":"man3/EVP_PKEY_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the OSSL_PROVIDER APIs.

EVP_PKEY_METHOD is a structure which holds a set of methods for a specific public key cryptographic algorithm. Those methods are usually used to perform different jobs, such as generating a key, signing or verifying, encrypting or decrypting, etc.

There are two places where the EVP_PKEY_METHOD objects are stored: one is a built-in static array representing the standard methods for different algorithms, and the other one is a stack of user-defined application-specific methods, which can be manipulated by using EVP_PKEY_meth_add0(3).

The EVP_PKEY_METHOD objects are usually referenced by EVP_PKEY_CTX objects.

"},{"location":"man3/EVP_PKEY_meth_new/#methods","title":"Methods","text":"

The methods are the underlying implementations of a particular public key algorithm present by the EVP_PKEY_CTX object.

int (*init) (EVP_PKEY_CTX *ctx);\nint (*copy) (EVP_PKEY_CTX *dst, const EVP_PKEY_CTX *src);\nvoid (*cleanup) (EVP_PKEY_CTX *ctx);\n

The init() method is called to initialize algorithm-specific data when a new EVP_PKEY_CTX is created. As opposed to init(), the cleanup() method is called when an EVP_PKEY_CTX is freed. The copy() method is called when an EVP_PKEY_CTX is being duplicated. Refer to EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_new_id(3), EVP_PKEY_CTX_free(3) and EVP_PKEY_CTX_dup(3).

int (*paramgen_init) (EVP_PKEY_CTX *ctx);\nint (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);\n

The paramgen_init() and paramgen() methods deal with key parameter generation. They are called by EVP_PKEY_paramgen_init(3) and EVP_PKEY_paramgen(3) to handle the parameter generation process.

int (*keygen_init) (EVP_PKEY_CTX *ctx);\nint (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);\n

The keygen_init() and keygen() methods are used to generate the actual key for the specified algorithm. They are called by EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3).

int (*sign_init) (EVP_PKEY_CTX *ctx);\nint (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,\n             const unsigned char *tbs, size_t tbslen);\n

The sign_init() and sign() methods are used to generate the signature of a piece of data using a private key. They are called by EVP_PKEY_sign_init(3) and EVP_PKEY_sign(3).

int (*verify_init) (EVP_PKEY_CTX *ctx);\nint (*verify) (EVP_PKEY_CTX *ctx,\n               const unsigned char *sig, size_t siglen,\n               const unsigned char *tbs, size_t tbslen);\n

The verify_init() and verify() methods are used to verify whether a signature is valid. They are called by EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

int (*verify_recover_init) (EVP_PKEY_CTX *ctx);\nint (*verify_recover) (EVP_PKEY_CTX *ctx,\n                       unsigned char *rout, size_t *routlen,\n                       const unsigned char *sig, size_t siglen);\n

The verify_recover_init() and verify_recover() methods are used to verify a signature and then recover the digest from the signature (for instance, a signature that was generated by RSA signing algorithm). They are called by EVP_PKEY_verify_recover_init(3) and EVP_PKEY_verify_recover(3).

int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);\nint (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,\n                EVP_MD_CTX *mctx);\n

The signctx_init() and signctx() methods are used to sign a digest present by a EVP_MD_CTX object. They are called by the EVP_DigestSign functions. See EVP_DigestSignInit(3) for details.

int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);\nint (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,\n                  EVP_MD_CTX *mctx);\n

The verifyctx_init() and verifyctx() methods are used to verify a signature against the data in a EVP_MD_CTX object. They are called by the various EVP_DigestVerify functions. See EVP_DigestVerifyInit(3) for details.

int (*encrypt_init) (EVP_PKEY_CTX *ctx);\nint (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,\n                const unsigned char *in, size_t inlen);\n

The encrypt_init() and encrypt() methods are used to encrypt a piece of data. They are called by EVP_PKEY_encrypt_init(3) and EVP_PKEY_encrypt(3).

int (*decrypt_init) (EVP_PKEY_CTX *ctx);\nint (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,\n                const unsigned char *in, size_t inlen);\n

The decrypt_init() and decrypt() methods are used to decrypt a piece of data. They are called by EVP_PKEY_decrypt_init(3) and EVP_PKEY_decrypt(3).

int (*derive_init) (EVP_PKEY_CTX *ctx);\nint (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);\n

The derive_init() and derive() methods are used to derive the shared secret from a public key algorithm (for instance, the DH algorithm). They are called by EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3).

int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);\nint (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);\n

The ctrl() and ctrl_str() methods are used to adjust algorithm-specific settings. See EVP_PKEY_CTX_ctrl(3) and related functions for details.

int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,\n                   const unsigned char *tbs, size_t tbslen);\nint (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,\n                     size_t siglen, const unsigned char *tbs,\n                     size_t tbslen);\n

The digestsign() and digestverify() methods are used to generate or verify a signature in a one-shot mode. They could be called by EVP_DigestSign(3) and EVP_DigestVerify(3).

int (*check) (EVP_PKEY *pkey);\nint (*public_check) (EVP_PKEY *pkey);\nint (*param_check) (EVP_PKEY *pkey);\n

The check(), public_check() and param_check() methods are used to validate a key-pair, the public component and parameters respectively for a given pkey. They could be called by EVP_PKEY_check(3), EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) respectively.

int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);\n

The digest_custom() method is used to generate customized digest content before the real message is passed to functions like EVP_DigestSignUpdate(3) or EVP_DigestVerifyInit(3). This is usually required by some public key signature algorithms like SM2 which requires a hashed prefix to the message to be signed. The digest_custom() function will be called by EVP_DigestSignInit(3) and EVP_DigestVerifyInit(3).

"},{"location":"man3/EVP_PKEY_meth_new/#functions","title":"Functions","text":"

EVP_PKEY_meth_new() creates and returns a new EVP_PKEY_METHOD object, and associates the given id and flags. The following flags are supported:

EVP_PKEY_FLAG_AUTOARGLEN\nEVP_PKEY_FLAG_SIGCTX_CUSTOM\n

If an EVP_PKEY_METHOD is set with the EVP_PKEY_FLAG_AUTOARGLEN flag, the maximum size of the output buffer will be automatically calculated or checked in corresponding EVP methods by the EVP framework. Thus the implementations of these methods don't need to care about handling the case of returning output buffer size by themselves. For details on the output buffer size, refer to EVP_PKEY_sign(3).

The EVP_PKEY_FLAG_SIGCTX_CUSTOM is used to indicate the signctx() method of an EVP_PKEY_METHOD is always called by the EVP framework while doing a digest signing operation by calling EVP_DigestSignFinal(3).

EVP_PKEY_meth_free() frees an existing EVP_PKEY_METHOD pointed by pmeth. If the argument is NULL, nothing is done.

EVP_PKEY_meth_copy() copies an EVP_PKEY_METHOD object from src to dst.

EVP_PKEY_meth_find() finds an EVP_PKEY_METHOD object with the id. This function first searches through the user-defined method objects and then the built-in objects.

EVP_PKEY_meth_add0() adds pmeth to the user defined stack of methods.

EVP_PKEY_meth_remove() removes an EVP_PKEY_METHOD object added by EVP_PKEY_meth_add0().

The EVP_PKEY_meth_set functions set the corresponding fields of EVP_PKEY_METHOD structure with the arguments passed.

The EVP_PKEY_meth_get functions get the corresponding fields of EVP_PKEY_METHOD structure to the arguments provided.

"},{"location":"man3/EVP_PKEY_meth_new/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_meth_new() returns a pointer to a new EVP_PKEY_METHOD object or returns NULL on error.

EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.

EVP_PKEY_meth_find() returns a pointer to the found EVP_PKEY_METHOD object or returns NULL if not found.

EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0 if an error occurred.

EVP_PKEY_meth_remove() returns 1 if method is removed successfully or 0 if an error occurred.

All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return values. For the 'get' functions, function pointers are returned by arguments.

"},{"location":"man3/EVP_PKEY_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The signature of the copy functional argument of EVP_PKEY_meth_set_copy() has changed in OpenSSL 3.0 so its src parameter is now constified.

"},{"location":"man3/EVP_PKEY_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2024 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.

"},{"location":"man3/EVP_PKEY_new/","title":"EVP_PKEY_new","text":""},{"location":"man3/EVP_PKEY_new/#name","title":"NAME","text":"

EVP_PKEY, EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_dup, EVP_PKEY_free, EVP_PKEY_new_raw_private_key_ex, EVP_PKEY_new_raw_private_key, EVP_PKEY_new_raw_public_key_ex, EVP_PKEY_new_raw_public_key, EVP_PKEY_new_CMAC_key, EVP_PKEY_new_mac_key, EVP_PKEY_get_raw_private_key, EVP_PKEY_get_raw_public_key - public/private key allocation and raw key handling functions

"},{"location":"man3/EVP_PKEY_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef evp_pkey_st EVP_PKEY;\n\nEVP_PKEY *EVP_PKEY_new(void);\nint EVP_PKEY_up_ref(EVP_PKEY *key);\nEVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key);\nvoid EVP_PKEY_free(EVP_PKEY *key);\n\nEVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx,\n                                          const char *keytype,\n                                          const char *propq,\n                                          const unsigned char *key,\n                                          size_t keylen);\nEVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e,\n                                       const unsigned char *key, size_t keylen);\nEVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx,\n                                         const char *keytype,\n                                         const char *propq,\n                                         const unsigned char *key,\n                                         size_t keylen);\nEVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e,\n                                      const unsigned char *key, size_t keylen);\nEVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key,\n                               int keylen);\n\nint EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv,\n                                 size_t *len);\nint EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub,\n                                size_t *len);\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,\n                                size_t len, const EVP_CIPHER *cipher);\n
"},{"location":"man3/EVP_PKEY_new/#description","title":"DESCRIPTION","text":"

EVP_PKEY is a generic structure to hold diverse types of asymmetric keys (also known as \"key pairs\"), and can be used for diverse operations, like signing, verifying signatures, key derivation, etc. The asymmetric keys themselves are often referred to as the \"internal key\", and are handled by backends, such as providers (through EVP_KEYMGMT(3)) or ENGINEs.

Conceptually, an EVP_PKEY internal key may hold a private key, a public key, or both (a keypair), and along with those, key parameters if the key type requires them. The presence of these components determine what operations can be made; for example, signing normally requires the presence of a private key, and verifying normally requires the presence of a public key.

EVP_PKEY has also been used for MAC algorithm that were conceived as producing signatures, although not being public key algorithms; \"POLY1305\", \"SIPHASH\", \"HMAC\", \"CMAC\". This usage is considered legacy and is discouraged in favor of the EVP_MAC(3) API.

The EVP_PKEY_new() function allocates an empty EVP_PKEY structure which is used by OpenSSL to store public and private keys. The reference count is set to 1.

EVP_PKEY_up_ref() increments the reference count of key.

EVP_PKEY_dup() duplicates the key. The key must not be ENGINE based or a raw key, otherwise the duplication will fail.

EVP_PKEY_free() decrements the reference count of key and, if the reference count is zero, frees it up. If key is NULL, nothing is done.

EVP_PKEY_new_raw_private_key_ex() allocates a new EVP_PKEY. Unless an engine should be used for the key type, a provider for the key is found using the library context libctx and the property query string propq. The keytype argument indicates what kind of key this is. The value should be a string for a public key algorithm that supports raw private keys, i.e one of \"X25519\", \"ED25519\", \"X448\" or \"ED448\". key points to the raw private key data for this EVP_PKEY which should be of length keylen. The length should be appropriate for the type of the key. The public key data will be automatically derived from the given private key data (if appropriate for the algorithm type).

EVP_PKEY_new_raw_private_key() does the same as EVP_PKEY_new_raw_private_key_ex() except that the default library context and default property query are used instead. If e is non-NULL then the new EVP_PKEY structure is associated with the engine e. The type argument indicates what kind of key this is. The value should be a NID for a public key algorithm that supports raw private keys, i.e. one of EVP_PKEY_X25519, EVP_PKEY_ED25519, EVP_PKEY_X448 or EVP_PKEY_ED448.

EVP_PKEY_new_raw_private_key_ex() and EVP_PKEY_new_raw_private_key() may also be used with most MACs implemented as public key algorithms, so key types such as \"HMAC\", \"POLY1305\", \"SIPHASH\", or their NID form EVP_PKEY_POLY1305, EVP_PKEY_SIPHASH, EVP_PKEY_HMAC are also accepted. This usage is, as mentioned above, discouraged in favor of the EVP_MAC(3) API.

EVP_PKEY_new_raw_public_key_ex() works in the same way as EVP_PKEY_new_raw_private_key_ex() except that key points to the raw public key data. The EVP_PKEY structure will be initialised without any private key information. Algorithm types that support raw public keys are \"X25519\", \"ED25519\", \"X448\" or \"ED448\".

EVP_PKEY_new_raw_public_key() works in the same way as EVP_PKEY_new_raw_private_key() except that key points to the raw public key data. The EVP_PKEY structure will be initialised without any private key information. Algorithm types that support raw public keys are EVP_PKEY_X25519, EVP_PKEY_ED25519, EVP_PKEY_X448 or EVP_PKEY_ED448.

EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). New applications should use EVP_PKEY_new_raw_private_key() instead.

EVP_PKEY_get_raw_private_key() fills the buffer provided by priv with raw private key data. The size of the priv buffer should be in *len on entry to the function, and on exit *len is updated with the number of bytes actually written. If the buffer priv is NULL then *len is populated with the number of bytes required to hold the key. The calling application is responsible for ensuring that the buffer is large enough to receive the private key data. This function only works for algorithms that support raw private keys. Currently this is: EVP_PKEY_HMAC, EVP_PKEY_POLY1305, EVP_PKEY_SIPHASH, EVP_PKEY_X25519, EVP_PKEY_ED25519, EVP_PKEY_X448 or EVP_PKEY_ED448.

EVP_PKEY_get_raw_public_key() fills the buffer provided by pub with raw public key data. The size of the pub buffer should be in *len on entry to the function, and on exit *len is updated with the number of bytes actually written. If the buffer pub is NULL then *len is populated with the number of bytes required to hold the key. The calling application is responsible for ensuring that the buffer is large enough to receive the public key data. This function only works for algorithms that support raw public keys. Currently this is: EVP_PKEY_X25519, EVP_PKEY_ED25519, EVP_PKEY_X448 or EVP_PKEY_ED448.

EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() except it is only for the EVP_PKEY_CMAC algorithm type. In addition to the raw private key data, it also takes a cipher algorithm to be used during creation of a CMAC in the cipher argument. The cipher should be a standard encryption-only cipher. For example AEAD and XTS ciphers should not be used.

Applications should use the EVP_MAC(3) API instead and set the OSSL_MAC_PARAM_CIPHER parameter on the EVP_MAC_CTX object with the name of the cipher being used.

"},{"location":"man3/EVP_PKEY_new/#notes","title":"NOTES","text":"

The EVP_PKEY structure is used by various OpenSSL functions which require a general private key without reference to any particular algorithm.

The structure returned by EVP_PKEY_new() is empty. To add a private or public key to this empty structure use the appropriate functions described in EVP_PKEY_set1_RSA(3), EVP_PKEY_set1_DSA(3), EVP_PKEY_set1_DH(3) or EVP_PKEY_set1_EC_KEY(3).

"},{"location":"man3/EVP_PKEY_new/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly allocated EVP_PKEY structure or NULL if an error occurred.

EVP_PKEY_dup() returns the key duplicate or NULL if an error occurred.

EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure.

"},{"location":"man3/EVP_PKEY_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_set1_RSA(3), EVP_PKEY_set1_DSA(3), EVP_PKEY_set1_DH(3) or EVP_PKEY_set1_EC_KEY(3)

"},{"location":"man3/EVP_PKEY_new/#history","title":"HISTORY","text":"

The EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL.

The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0.

The EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1.

The EVP_PKEY_dup(), EVP_PKEY_new_raw_private_key_ex(), and EVP_PKEY_new_raw_public_key_ex() functions were added in OpenSSL 3.0.

The EVP_PKEY_new_CMAC_key() was deprecated in OpenSSL 3.0.

The documentation of EVP_PKEY was amended in OpenSSL 3.0 to allow there to be the private part of the keypair without the public part, where this was previously implied to be disallowed.

"},{"location":"man3/EVP_PKEY_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2022 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.

"},{"location":"man3/EVP_PKEY_print_private/","title":"EVP_PKEY_print_private","text":""},{"location":"man3/EVP_PKEY_print_private/#name","title":"NAME","text":"

EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params, EVP_PKEY_print_public_fp, EVP_PKEY_print_private_fp, EVP_PKEY_print_params_fp - public key algorithm printing routines

"},{"location":"man3/EVP_PKEY_print_private/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey,\n                          int indent, ASN1_PCTX *pctx);\nint EVP_PKEY_print_public_fp(FILE *fp, const EVP_PKEY *pkey,\n                             int indent, ASN1_PCTX *pctx);\nint EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey,\n                           int indent, ASN1_PCTX *pctx);\nint EVP_PKEY_print_private_fp(FILE *fp, const EVP_PKEY *pkey,\n                              int indent, ASN1_PCTX *pctx);\nint EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey,\n                          int indent, ASN1_PCTX *pctx);\nint EVP_PKEY_print_params_fp(FILE *fp, const EVP_PKEY *pkey,\n                             int indent, ASN1_PCTX *pctx);\n
"},{"location":"man3/EVP_PKEY_print_private/#description","title":"DESCRIPTION","text":"

The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and EVP_PKEY_print_params() print out the public, private or parameter components of key pkey respectively. The key is sent to BIO out in human readable form. The parameter indent indicates how far the printout should be indented.

The pctx parameter allows the print output to be finely tuned by using ASN1 printing options. If pctx is set to NULL then default values will be used.

The functions EVP_PKEY_print_public_fp(), EVP_PKEY_print_private_fp() and EVP_PKEY_print_params_fp() do the same as the BIO based functions but use FILE fp instead.

"},{"location":"man3/EVP_PKEY_print_private/#notes","title":"NOTES","text":"

Currently no public key algorithms include any options in the pctx parameter.

If the key does not include all the components indicated by the function then only those contained in the key will be printed. For example passing a public key to EVP_PKEY_print_private() will only print the public components.

"},{"location":"man3/EVP_PKEY_print_private/#return-values","title":"RETURN VALUES","text":"

These functions all return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_print_private/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_keygen(3)

"},{"location":"man3/EVP_PKEY_print_private/#history","title":"HISTORY","text":"

The functions EVP_PKEY_print_public(), EVP_PKEY_print_private(), and EVP_PKEY_print_params() were added in OpenSSL 1.0.0.

The functions EVP_PKEY_print_public_fp(), EVP_PKEY_print_private_fp(), and EVP_PKEY_print_params_fp() were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_print_private/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 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.

"},{"location":"man3/EVP_PKEY_set1_RSA/","title":"EVP_PKEY_set1_RSA","text":""},{"location":"man3/EVP_PKEY_set1_RSA/#name","title":"NAME","text":"

EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id, EVP_PKEY_set1_engine, EVP_PKEY_get0_engine, EVP_PKEY_id, EVP_PKEY_base_id - EVP_PKEY assignment functions

"},{"location":"man3/EVP_PKEY_set1_RSA/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_get_id(const EVP_PKEY *pkey);\nint EVP_PKEY_get_base_id(const EVP_PKEY *pkey);\nint EVP_PKEY_type(int type);\n\n#define EVP_PKEY_id EVP_PKEY_get_id\n#define EVP_PKEY_base_id EVP_PKEY_get_base_id\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);\nint EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);\nint EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);\nint EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);\n\nRSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);\nDSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);\nDH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);\nEC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);\n\nconst unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);\nconst unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);\nconst unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);\nconst RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);\nconst DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);\nconst DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);\nconst EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);\nvoid *EVP_PKEY_get0(const EVP_PKEY *pkey);\n\nint EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);\nint EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);\nint EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);\nint EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);\nint EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);\nint EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);\n\nENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);\nint EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);\n
"},{"location":"man3/EVP_PKEY_set1_RSA/#description","title":"DESCRIPTION","text":"

EVP_PKEY_get_base_id() returns the type of pkey. For example an RSA key will return EVP_PKEY_RSA.

EVP_PKEY_get_id() returns the actual NID associated with pkey only if the pkey type isn't implemented just in a provider(7). Historically keys using the same algorithm could use different NIDs. For example an RSA key could use the NIDs corresponding to the NIDs NID_rsaEncryption (equivalent to EVP_PKEY_RSA) or NID_rsa (equivalent to EVP_PKEY_RSA2). The use of alternative non-standard NIDs is now rare so EVP_PKEY_RSA2 et al are not often seen in practice. EVP_PKEY_get_id() returns -1 (EVP_PKEY_KEYMGMT) if the pkey is only implemented in a provider(7).

EVP_PKEY_type() returns the underlying type of the NID type. For example EVP_PKEY_type(EVP_PKEY_RSA2) will return EVP_PKEY_RSA.

EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and EVP_PKEY_set1_EC_KEY() set the key referenced by pkey to key. These functions are deprecated. Applications should instead use EVP_PKEY_fromdata(3).

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() set the referenced key to key however these use the supplied key internally and so key will be freed when the parent pkey is freed. These macros are deprecated. Applications should instead read an EVP_PKEY directly using the OSSL_DECODER APIs (see OSSL_DECODER_CTX_new_for_pkey(3)), or construct an EVP_PKEY from data using EVP_PKEY_fromdata(3).

EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in pkey or NULL if the key is not of the correct type. The returned key must be freed after use. These functions are deprecated. Applications should instead use the EVP_PKEY directly where possible. If access to the low level key parameters is required then applications should use EVP_PKEY_get_params(3) and other similar functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see OSSL_ENCODER_CTX_new_for_pkey(3)).

EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() return the referenced key in pkey or NULL if the key is not of the correct type. The reference count of the returned key is not incremented and so the key must not be freed after use. These functions are deprecated. Applications should instead use the EVP_PKEY directly where possible. If access to the low level key parameters is required then applications should use EVP_PKEY_get_params(3) and other similar functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see OSSL_ENCODER_CTX_new_for_pkey(3)). EVP_PKEY_get0() returns a pointer to the legacy key or NULL if the key is not legacy.

Note that if an EVP_PKEY was not constructed using one of the deprecated functions such as EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() or EVP_PKEY_set1_EC_KEY(), or via the similarly named EVP_PKEY_assign macros described above then the internal key will be managed by a provider (see provider(7)). In that case the key returned by EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_EC_KEY(), EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() or EVP_PKEY_get0_EC_KEY() will be a cached copy of the provider's key. Subsequent updates to the provider's key will not be reflected back in the cached copy, and updates made by an application to the returned key will not be reflected back in the provider's key. Subsequent calls to EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() will always return the cached copy returned by the first call.

EVP_PKEY_get0_engine() returns a reference to the ENGINE handling pkey. This function is deprecated. Applications should use providers instead of engines (see provider(7) for details).

EVP_PKEY_set1_engine() sets the ENGINE handling pkey to engine. It must be called after the key algorithm and components are set up. If engine does not include an EVP_PKEY_METHOD for pkey an error occurs. This function is deprecated. Applications should use providers instead of engines (see provider(7) for details).

"},{"location":"man3/EVP_PKEY_set1_RSA/#warnings","title":"WARNINGS","text":"

The following functions are only reliable with EVP_PKEYs that have been assigned an internal key with EVP_PKEY_assign_*():

EVP_PKEY_get_id(), EVP_PKEY_get_base_id(), EVP_PKEY_type()

For EVP_PKEY key type checking purposes, EVP_PKEY_is_a(3) is more generic.

For purposes of retrieving the name of the EVP_PKEY the function EVP_PKEY_get0_type_name(3) is more generally useful.

The keys returned from the functions EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() were changed to have a \"const\" return type in OpenSSL 3.0. As described above the keys returned may be cached copies of the key held in a provider. Due to this, and unlike in earlier versions of OpenSSL, they should be considered read-only copies of the key. Updates to these keys will not be reflected back in the provider side key. The EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() functions were not changed to have a \"const\" return type in order that applications can \"free\" the return value. However applications should still consider them as read-only copies.

"},{"location":"man3/EVP_PKEY_set1_RSA/#notes","title":"NOTES","text":"

In accordance with the OpenSSL naming convention the key obtained from or assigned to the pkey using the 1 functions must be freed as well as pkey.

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() are implemented as macros.

EVP_PKEY_assign_EC_KEY() looks at the curve name id to determine if the passed EC_KEY is an SM2(7) key, and will set the EVP_PKEY type to EVP_PKEY_SM2 in that case, instead of EVP_PKEY_EC.

Most applications wishing to know a key type will simply call EVP_PKEY_get_base_id() and will not care about the actual type: which will be identical in almost all cases.

Previous versions of this document suggested using EVP_PKEY_type(pkey->type) to determine the type of a key. Since EVP_PKEY is now opaque this is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey).

EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM key as part of its routine to load a private key.

"},{"location":"man3/EVP_PKEY_set1_RSA/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.

EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if an error occurred.

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() return 1 for success and 0 for failure.

EVP_PKEY_get_base_id(), EVP_PKEY_get_id() and EVP_PKEY_type() return a key type or NID_undef (equivalently EVP_PKEY_NONE) on error.

EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.

"},{"location":"man3/EVP_PKEY_set1_RSA/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), SM2(7)

"},{"location":"man3/EVP_PKEY_set1_RSA/#history","title":"HISTORY","text":"

The EVP_PKEY_id() and EVP_PKEY_base_id() functions were renamed to include get in their names in OpenSSL 3.0, respectively. The old names are kept as non-deprecated alias macros.

EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were deprecated in OpenSSL 3.0.

The return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0.

The function EVP_PKEY_set_alias_type() was previously documented on this page. It was removed in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_set1_RSA/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2023 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.

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/","title":"EVP_PKEY_set1_encoded_public_key","text":""},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#name","title":"NAME","text":"

EVP_PKEY_set1_encoded_public_key, EVP_PKEY_get1_encoded_public_key, EVP_PKEY_set1_tls_encodedpoint, EVP_PKEY_get1_tls_encodedpoint - functions to set and get public key data within an EVP_PKEY

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_set1_encoded_public_key(EVP_PKEY *pkey,\n                                     const unsigned char *pub, size_t publen);\n\nsize_t EVP_PKEY_get1_encoded_public_key(EVP_PKEY *pkey, unsigned char **ppub);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EVP_PKEY_set1_tls_encodedpoint(EVP_PKEY *pkey,\n                                   const unsigned char *pt, size_t ptlen);\n\nsize_t EVP_PKEY_get1_tls_encodedpoint(EVP_PKEY *pkey, unsigned char **ppt);\n
"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#description","title":"DESCRIPTION","text":"

EVP_PKEY_set1_encoded_public_key() can be used to set the public key value within an existing EVP_PKEY object. For the built-in OpenSSL algorithms this currently only works for those that support key exchange. Parameters are not set as part of this operation, so typically an application will create an EVP_PKEY first, set the parameters on it, and then call this function. For example setting the parameters might be done using EVP_PKEY_copy_parameters(3).

The format for the encoded public key will depend on the algorithm in use. For DH it should be encoded as a positive integer in big-endian form. For EC is should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 (\"Elliptic Curve Cryptography\") standard. For X25519 and X448 it should be encoded in a format as defined by RFC7748.

The key to be updated is supplied in pkey. The buffer containing the encoded key is pointed to be pub. The length of the buffer is supplied in publen.

EVP_PKEY_get1_encoded_public_key() does the equivalent operation except that the encoded public key is returned to the application. The key containing the public key data is supplied in pkey. A buffer containing the encoded key will be allocated and stored in *ppub. The length of the encoded public key is returned by the function. The application is responsible for freeing the allocated buffer.

The macro EVP_PKEY_set1_tls_encodedpoint() is deprecated and simply calls EVP_PKEY_set1_encoded_public_key() with all the same arguments. New applications should use EVP_PKEY_set1_encoded_public_key() instead.

The macro EVP_PKEY_get1_tls_encodedpoint() is deprecated and simply calls EVP_PKEY_get1_encoded_public_key() with all the same arguments. New applications should use EVP_PKEY_get1_encoded_public_key() instead.

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_set1_encoded_public_key() returns 1 for success and 0 or a negative value for failure.

EVP_PKEY_get1_encoded_public_key() returns the length of the encoded key or 0 for failure.

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#examples","title":"EXAMPLES","text":"

See EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3) for information about performing a key exchange operation.

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#set-up-a-peers-evp_pkey-ready-for-a-key-exchange-operation","title":"Set up a peer's EVP_PKEY ready for a key exchange operation","text":"
#include <openssl/evp.h>\n\nint exchange(EVP_PKEY *ourkey, unsigned char *peer_pub, size_t peer_pub_len)\n{\n    EVP_PKEY *peerkey = EVP_PKEY_new();\n\n    if (peerkey == NULL || EVP_PKEY_copy_parameters(peerkey, ourkey) <= 0)\n        return 0;\n\n    if (EVP_PKEY_set1_encoded_public_key(peerkey, peer_pub,\n                                         peer_pub_len) <= 0)\n        return 0;\n\n    /* Do the key exchange here */\n\n    EVP_PKEY_free(peerkey);\n\n    return 1;\n}\n
"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#get-an-encoded-public-key-to-send-to-a-peer","title":"Get an encoded public key to send to a peer","text":"
#include <openssl/evp.h>\n\nint get_encoded_pub_key(EVP_PKEY *ourkey)\n{\n    unsigned char *pubkey;\n    size_t pubkey_len;\n\n   pubkey_len = EVP_PKEY_get1_encoded_public_key(ourkey, &pubkey);\n   if (pubkey_len == 0)\n       return 0;\n\n   /*\n    * Send the encoded public key stored in the buffer at \"pubkey\" and of\n    * length pubkey_len, to the peer.\n    */\n\n   OPENSSL_free(pubkey);\n   return 1;\n}\n
"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), EVP_PKEY_copy_parameters(3), EVP_PKEY_derive_init(3), EVP_PKEY_derive(3), EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-X25519(7), EVP_PKEY-X448(7)

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#history","title":"HISTORY","text":"

EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key() were added in OpenSSL 3.0.

EVP_PKEY_set1_tls_encodedpoint() and EVP_PKEY_get1_tls_encodedpoint() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_set1_encoded_public_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/EVP_PKEY_set_type/","title":"EVP_PKEY_set_type","text":""},{"location":"man3/EVP_PKEY_set_type/#name","title":"NAME","text":"

EVP_PKEY_set_type, EVP_PKEY_set_type_str, EVP_PKEY_set_type_by_keymgmt - functions to change the EVP_PKEY type

"},{"location":"man3/EVP_PKEY_set_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_set_type(EVP_PKEY *pkey, int type);\nint EVP_PKEY_set_type_str(EVP_PKEY *pkey, const char *str, int len);\nint EVP_PKEY_set_type_by_keymgmt(EVP_PKEY *pkey, EVP_KEYMGMT *keymgmt);\n
"},{"location":"man3/EVP_PKEY_set_type/#description","title":"DESCRIPTION","text":"

All the functions described here behave the same in so far that they clear all the previous key data and methods from pkey, and reset it to be of the type of key given by the different arguments. If pkey is NULL, these functions will still return the same return values as if it wasn't.

EVP_PKEY_set_type() initialises pkey to contain an internal legacy key. When doing this, it finds a EVP_PKEY_ASN1_METHOD(3) corresponding to type, and associates pkey with the findings. It is an error if no EVP_PKEY_ASN1_METHOD(3) could be found for type.

EVP_PKEY_set_type_str() initialises pkey to contain an internal legacy key. When doing this, it finds a EVP_PKEY_ASN1_METHOD(3) corresponding to str that has then length len, and associates pkey with the findings. It is an error if no EVP_PKEY_ASN1_METHOD(3) could be found for type.

For both EVP_PKEY_set_type() and EVP_PKEY_set_type_str(), pkey gets a numeric type, which can be retrieved with EVP_PKEY_get_id(3). This numeric type is taken from the EVP_PKEY_ASN1_METHOD(3) that was found, and is equal to or closely related to type in the case of EVP_PKEY_set_type(), or related to str in the case of EVP_PKEY_set_type_str().

EVP_PKEY_set_type_by_keymgmt() initialises pkey to contain an internal provider side key. When doing this, it associates pkey with keymgmt. For keys initialised like this, the numeric type retrieved with EVP_PKEY_get_id(3) will always be EVP_PKEY_NONE.

"},{"location":"man3/EVP_PKEY_set_type/#return-values","title":"RETURN VALUES","text":"

All functions described here return 1 if successful, or 0 on error.

"},{"location":"man3/EVP_PKEY_set_type/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_assign(3), EVP_PKEY_get_id(3), EVP_PKEY_get0_RSA(3), EVP_PKEY_copy_parameters(3), EVP_PKEY_ASN1_METHOD(3), EVP_KEYMGMT(3)

"},{"location":"man3/EVP_PKEY_set_type/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_settable_params/","title":"EVP_PKEY_settable_params","text":""},{"location":"man3/EVP_PKEY_settable_params/#name","title":"NAME","text":"

EVP_PKEY_settable_params, EVP_PKEY_set_params, EVP_PKEY_set_int_param, EVP_PKEY_set_size_t_param, EVP_PKEY_set_bn_param, EVP_PKEY_set_utf8_string_param, EVP_PKEY_set_octet_string_param - set key parameters into a key

"},{"location":"man3/EVP_PKEY_settable_params/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst OSSL_PARAM *EVP_PKEY_settable_params(const EVP_PKEY *pkey);\nint EVP_PKEY_set_params(EVP_PKEY *pkey, OSSL_PARAM params[]);\nint EVP_PKEY_set_int_param(EVP_PKEY *pkey, const char *key_name, int in);\nint EVP_PKEY_set_size_t_param(EVP_PKEY *pkey, const char *key_name, size_t in);\nint EVP_PKEY_set_bn_param(EVP_PKEY *pkey, const char *key_name,\n                          const BIGNUM *bn);\nint EVP_PKEY_set_utf8_string_param(EVP_PKEY *pkey, const char *key_name,\n                                   const char *str);\nint EVP_PKEY_set_octet_string_param(EVP_PKEY *pkey, const char *key_name,\n                                    const unsigned char *buf, size_t bsize);\n
"},{"location":"man3/EVP_PKEY_settable_params/#description","title":"DESCRIPTION","text":"

These functions can be used to set additional parameters into an existing EVP_PKEY.

EVP_PKEY_set_params() sets one or more params into a pkey. See OSSL_PARAM(3) for information about parameters.

EVP_PKEY_settable_params() returns a constant list of params indicating the names and types of key parameters that can be set. See OSSL_PARAM(3) for information about parameters.

EVP_PKEY_set_int_param() sets an integer value in into a key pkey for the associated field key_name.

EVP_PKEY_set_size_t_param() sets an size_t value in into a key pkey for the associated field key_name.

EVP_PKEY_set_bn_param() sets the BIGNUM value bn into a key pkey for the associated field key_name.

EVP_PKEY_set_utf8_string_param() sets the UTF8 string str into a key pkey for the associated field key_name.

EVP_PKEY_set_octet_string_param() sets the octet string value buf with a size bsize into a key pkey for the associated field key_name.

"},{"location":"man3/EVP_PKEY_settable_params/#notes","title":"NOTES","text":"

These functions only work for EVP_PKEYs that contain a provider side key.

"},{"location":"man3/EVP_PKEY_settable_params/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_settable_params() returns NULL on error or if it is not supported,

All other methods return 1 if a value was successfully set, or 0 if there was an error.

"},{"location":"man3/EVP_PKEY_settable_params/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_gettable_params(3), EVP_PKEY_CTX_new(3), provider-keymgmt(7), OSSL_PARAM(3),

"},{"location":"man3/EVP_PKEY_settable_params/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_settable_params/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 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.

"},{"location":"man3/EVP_PKEY_sign/","title":"EVP_PKEY_sign","text":""},{"location":"man3/EVP_PKEY_sign/#name","title":"NAME","text":"

EVP_PKEY_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init_ex2, EVP_PKEY_sign, EVP_PKEY_sign_message_init, EVP_PKEY_sign_message_update, EVP_PKEY_sign_message_final - sign using a public key algorithm

"},{"location":"man3/EVP_PKEY_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_sign_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,\n                           const OSSL_PARAM params[]);\nint EVP_PKEY_sign_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,\n                               const OSSL_PARAM params[]);\nint EVP_PKEY_sign_message_update(EVP_PKEY_CTX *ctx,\n                                 unsigned char *in, size_t inlen);\nint EVP_PKEY_sign_message_final(EVP_PKEY_CTX *ctx, unsigned char *sig,\n                                size_t *siglen, size_t sigsize);\nint EVP_PKEY_sign(EVP_PKEY_CTX *ctx,\n                  unsigned char *sig, size_t *siglen,\n                  const unsigned char *tbs, size_t tbslen);\n
"},{"location":"man3/EVP_PKEY_sign/#description","title":"DESCRIPTION","text":"

EVP_PKEY_sign_init() initializes a public key algorithm context ctx for signing using the algorithm given when the context was created using EVP_PKEY_CTX_new(3) or variants thereof. The algorithm is used to fetch a EVP_SIGNATURE method implicitly, see \"Implicit fetch\" in provider(7) for more information about implicit fetches.

EVP_PKEY_sign_init_ex() is the same as EVP_PKEY_sign_init() but additionally sets the passed parameters params on the context before returning.

EVP_PKEY_sign_init_ex2() initializes a public key algorithm context ctx for signing a pre-computed message digest using the algorithm given by algo and the key given through EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3). A context ctx without a pre-loaded key cannot be used with this function. This function provides almost the same functionality as EVP_PKEY_sign_init_ex(), but is uniquely intended to be used with a pre-computed messsage digest, and allows pre-determining the exact conditions for that message digest, if a composite signature algorithm (such as RSA-SHA256) was fetched. Following a call to this function, setting parameters that modifies the digest implementation or padding is not normally supported.

EVP_PKEY_sign_message_init() initializes a public key algorithm context ctx for signing an unlimited size message using the algorithm given by algo and the key given through EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3). Passing the message is supported both in a one-shot fashion using EVP_PKEY_sign(), and through the combination of EVP_PKEY_sign_message_update() and EVP_PKEY_sign_message_final(). This function enables using algorithms that can process input of arbitrary length, such as ED25519, RSA-SHA256 and similar.

EVP_PKEY_sign_message_update() adds inlen bytes from in to the data to be processed for signature. The signature algorithm specification and implementation determine how the input bytes are processed and if there's a limit on the total size of the input. See \"NOTES\" below for a deeper explanation.

EVP_PKEY_sign_message_final() signs the processed data and places the data in sig, and the number of signature bytes in *siglen, if the number of bytes doesn't surpass the size given by sigsize. sig may be NULL, and in that case, only *siglen is updated with the number of signature bytes.

EVP_PKEY_sign() is a one-shot function that can be used with all the init functions above. When initialization was done with EVP_PKEY_sign_init(), EVP_PKEY_sign_init_ex() or EVP_PKEY_sign_init_ex2(), the data specified by tbs and tbslen is signed after appropriate padding. When initialization was done with EVP_PKEY_sign_message_init(), the data specified by tbs and tbslen is digested by the implied message digest algorithm, and the result is signed after appropriate padding. If sig is NULL then the maximum size of the output buffer is written to the siglen parameter. If sig is not NULL, then before the call the siglen parameter should contain the length of the sig buffer, and if the call is successful the signature is written to sig and the amount of data written to siglen.

"},{"location":"man3/EVP_PKEY_sign/#notes","title":"NOTES","text":""},{"location":"man3/EVP_PKEY_sign/#general","title":"General","text":"

Some signature implementations only accumulate the input data and do no further processing before signing it (they expect the input to be a digest), while others compress the data, typically by internally producing a digest, and signing the result. Some of them support both modes of operation at the same time. The caller is expected to know how the chosen algorithm is supposed to behave and under what conditions.

For example, an RSA implementation can be expected to only expect a message digest as input, while ED25519 can be expected to process the input with a hash, i.e. to produce the message digest internally, and while RSA-SHA256 can be expected to handle either mode of operation, depending on if the operation was initialized with EVP_PKEY_sign_init_ex2() or with EVP_PKEY_sign_message_init().

Similarly, an RSA implementation usually expects additional details to be set, like the message digest algorithm that the input is supposed to be digested with, as well as the padding mode (see EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_padding(3) and similar others), while an RSA-SHA256 implementation usually has these details pre-set and immutable.

The functions described here can't be used to combine separate algorithms. In particular, neither EVP_PKEY_CTX_set_signature_md(3) nor the OSSL_PARAM parameter \"digest\" (OSSL_SIGNATURE_PARAM_DIGEST) can be used to combine a signature algorithm with a hash algorithm to process the input. In other words, it's not possible to specify a ctx pre-loaded with an RSA pkey, or an algo that fetched RSA and try to specify SHA256 separately to get the functionality of RSA-SHA256. If combining algorithms in that manner is desired, please use EVP_DigestSignInit(3) and associated functions.

"},{"location":"man3/EVP_PKEY_sign/#performing-multiple-signatures","title":"Performing multiple signatures","text":"

When initialized using EVP_PKEY_sign_init_ex() or EVP_PKEY_sign_init_ex2(), EVP_PKEY_sign() can be called more than once on the same context to have several one-shot operations performed using the same parameters.

When initialized using EVP_PKEY_sign_message_init(), it's not possible to call EVP_PKEY_sign() multiple times.

"},{"location":"man3/EVP_PKEY_sign/#return-values","title":"RETURN VALUES","text":"

All functions return 1 for success and 0 or a negative value for failure.

In particular, EVP_PKEY_sign_init() and its other variants may return -2 to indicate that the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_sign/#examples","title":"EXAMPLES","text":""},{"location":"man3/EVP_PKEY_sign/#rsa-with-pkcs1-padding-for-sha256","title":"RSA with PKCS#1 padding for SHA256","text":"

Sign data using RSA with PKCS#1 padding and a SHA256 digest as input:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* md is a SHA-256 digest in this example. */\nunsigned char *md, *sig;\nsize_t mdlen = 32, siglen;\nEVP_PKEY *signing_key;\n\n/*\n * NB: assumes signing_key and md are set up before the next\n * step. signing_key must be an RSA private key and md must\n * point to the SHA-256 digest to be signed.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nif (ctx == NULL)\n    /* Error occurred */\nif (EVP_PKEY_sign_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)\n    /* Error */\n\nsig = OPENSSL_malloc(siglen);\n\nif (sig == NULL)\n    /* malloc failure */\n\nif (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)\n    /* Error */\n\n/* Signature is siglen bytes written to buffer sig */\n
"},{"location":"man3/EVP_PKEY_sign/#rsa-sha256-with-a-pre-computed-digest","title":"RSA-SHA256 with a pre-computed digest","text":"

Sign a digest with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of sha256WithRSAEncryption, for which the padding is pre-determined to be RSA_PKCS1_PADDING, and the input digest is assumed to have been computed using SHA256.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* md is a SHA-256 digest in this example. */\nunsigned char *md, *sig;\nsize_t mdlen = 32, siglen;\nEVP_PKEY *signing_key;\n\n/*\n * NB: assumes signing_key and md are set up before the next\n * step. signing_key must be an RSA private key and md must\n * point to the SHA-256 digest to be signed.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL)\n    /* Error occurred */\nif (EVP_PKEY_sign_init_ex2(ctx, alg, NULL) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)\n    /* Error */\n\nsig = OPENSSL_malloc(siglen);\n\nif (sig == NULL)\n    /* malloc failure */\n\nif (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)\n    /* Error */\n\n/* Signature is siglen bytes written to buffer sig */\n
"},{"location":"man3/EVP_PKEY_sign/#rsa-sha256-one-shot","title":"RSA-SHA256, one-shot","text":"

Sign a document with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of sha256WithRSAEncryption, for which the padding is pre-determined to be RSA_PKCS1_PADDING.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* in is the input in this example. */\nunsigned char *in, *sig;\n/* inlen is the length of the input in this example. */\nsize_t inlen, siglen;\nEVP_PKEY *signing_key;\nEVP_SIGNATURE *alg;\n\n/*\n * NB: assumes signing_key, in and inlen are set up before\n * the next step. signing_key must be an RSA private key,\n * in must point to data to be digested and signed, and\n * inlen must be the size of the data in bytes.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL || alg == NULL)\n    /* Error occurred */\nif (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0)\n    /* Error */\n\n/* Determine sig buffer length */\nif (EVP_PKEY_sign(ctx, NULL, &siglen, in, inlen) <= 0)\n    /* Error */\n\nsig = OPENSSL_malloc(siglen);\n\nif (sig == NULL)\n    /* malloc failure */\n\nif (EVP_PKEY_sign(ctx, sig, &siglen, in, inlen) <= 0)\n    /* Error */\n\n/* Signature is siglen bytes written to buffer sig */\n
"},{"location":"man3/EVP_PKEY_sign/#rsa-sha256-using-update-and-final","title":"RSA-SHA256, using update and final","text":"

This is the same as the previous example, but allowing stream-like functionality.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* in is the input in this example. */\nunsigned char *in, *sig;\n/* inlen is the length of the input in this example. */\nsize_t inlen, siglen;\nEVP_PKEY *signing_key;\nEVP_SIGNATURE *alg;\n\n/*\n * NB: assumes signing_key, in and inlen are set up before\n * the next step. signing_key must be an RSA private key,\n * in must point to data to be digested and signed, and\n * inlen must be the size of the data in bytes.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL || alg == NULL)\n    /* Error occurred */\nif (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0)\n    /* Error */\n\nwhile (inlen > 0) {\n    if (EVP_PKEY_sign_message_update(ctx, in, inlen)) <= 0)\n        /* Error */\n    if (inlen > 256) {\n        inlen -= 256;\n        in += 256;\n    } else {\n        inlen = 0;\n    }\n}\n\n/* Determine sig buffer length */\nif (EVP_PKEY_sign_message_final(ctx, NULL, &siglen) <= 0)\n    /* Error */\n\nsig = OPENSSL_malloc(siglen);\n\nif (sig == NULL)\n    /* malloc failure */\n\nif (EVP_PKEY_sign_message_final(ctx, sig, &siglen) <= 0)\n    /* Error */\n\n/* Signature is siglen bytes written to buffer sig */\n
"},{"location":"man3/EVP_PKEY_sign/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_sign/#history","title":"HISTORY","text":"

The EVP_PKEY_sign_init() and EVP_PKEY_sign() functions were added in OpenSSL 1.0.0.

The EVP_PKEY_sign_init_ex() function was added in OpenSSL 3.0.

The EVP_PKEY_sign_init_ex2(), EVP_PKEY_sign_message_init(), EVP_PKEY_sign_message_update() and EVP_PKEY_sign_message_final() functions where added in OpenSSL 3.4.

"},{"location":"man3/EVP_PKEY_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_PKEY_todata/","title":"EVP_PKEY_todata","text":""},{"location":"man3/EVP_PKEY_todata/#name","title":"NAME","text":"

EVP_PKEY_todata, EVP_PKEY_export - functions to return keys as an array of key parameters

"},{"location":"man3/EVP_PKEY_todata/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_todata(const EVP_PKEY *pkey, int selection, OSSL_PARAM **params);\nint EVP_PKEY_export(const EVP_PKEY *pkey, int selection,\n                    OSSL_CALLBACK *export_cb, void *export_cbarg);\n
"},{"location":"man3/EVP_PKEY_todata/#description","title":"DESCRIPTION","text":"

The functions described here are used to extract EVP_PKEY key values as an array of OSSL_PARAM(3).

EVP_PKEY_todata() extracts values from a key pkey using the selection. selection is described in \"Selections\" in EVP_PKEY_fromdata(3). OSSL_PARAM_free(3) should be used to free the returned parameters in *params.

EVP_PKEY_export() is similar to EVP_PKEY_todata() but uses a callback export_cb that gets passed the value of export_cbarg. See openssl-core.h(7) for more information about the callback. Note that the OSSL_PARAM(3) array that is passed to the callback is not persistent after the callback returns. The user must preserve the items of interest, or use EVP_PKEY_todata() if persistence is required.

"},{"location":"man3/EVP_PKEY_todata/#notes","title":"NOTES","text":"

These functions only work with key management methods coming from a provider. This is the mirror function to EVP_PKEY_fromdata(3).

"},{"location":"man3/EVP_PKEY_todata/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_todata() and EVP_PKEY_export() return 1 for success and 0 for failure.

"},{"location":"man3/EVP_PKEY_todata/#see-also","title":"SEE ALSO","text":"

OSSL_PARAM(3), openssl-core.h(7), EVP_PKEY_fromdata(3), EVP_PKEY-RSA(7), EVP_PKEY-DSA(7), EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-ED448(7), EVP_PKEY-X25519(7), EVP_PKEY-X448(7), EVP_PKEY-ED25519(7)

"},{"location":"man3/EVP_PKEY_todata/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_todata/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2022 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.

"},{"location":"man3/EVP_PKEY_verify/","title":"EVP_PKEY_verify","text":""},{"location":"man3/EVP_PKEY_verify/#name","title":"NAME","text":"

EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init_ex2, EVP_PKEY_verify, EVP_PKEY_verify_message_init, EVP_PKEY_verify_message_update, EVP_PKEY_verify_message_final, EVP_PKEY_CTX_set_signature - signature verification using a public key algorithm

"},{"location":"man3/EVP_PKEY_verify/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);\nint EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,\n                             const OSSL_PARAM params[]);\nint EVP_PKEY_verify_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,\n                                 const OSSL_PARAM params[]);\nint EVP_PKEY_CTX_set_signature(EVP_PKEY_CTX *pctx,\n                               const unsigned char *sig, size_t siglen);\nint EVP_PKEY_verify_message_update(EVP_PKEY_CTX *ctx,\n                                   unsigned char *in, size_t inlen);\nint EVP_PKEY_verify_message_final(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_verify(EVP_PKEY_CTX *ctx,\n                    const unsigned char *sig, size_t siglen,\n                    const unsigned char *tbs, size_t tbslen);\n
"},{"location":"man3/EVP_PKEY_verify/#description","title":"DESCRIPTION","text":"

EVP_PKEY_verify_init() initializes a public key algorithm context ctx for verification using the algorithm given when the context was created using EVP_PKEY_CTX_new(3) or variants thereof. The algorithm is used to fetch a EVP_SIGNATURE method implicitly, see \"Implicit fetch\" in provider(7) for more information about implicit fetches.

EVP_PKEY_verify_init_ex() is the same as EVP_PKEY_verify_init() but additionally sets the passed parameters params on the context before returning.

EVP_PKEY_verify_init_ex2() is the same as EVP_PKEY_verify_init_ex(), but works with an explicitly fetched EVP_SIGNATURE algo. A context ctx without a pre-loaded key cannot be used with this function. Depending on what algorithm was fetched, certain details revolving around the treatment of the input to EVP_PKEY_verify() may be pre-determined, and in that case, those details may normally not be changed. See \"NOTES\" below for a deeper explanation.

EVP_PKEY_verify_message_init() initializes a public key algorithm context ctx for verifying an unlimited size message using the algorithm given by algo and the key given through EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3). Passing the message is supported both in a one-shot fashion using EVP_PKEY_verify(), and through the combination of EVP_PKEY_verify_update() and EVP_PKEY_verify_final(). This function enables using algorithms that can process input of arbitrary length, such as ED25519, RSA-SHA256 and similar.

EVP_PKEY_CTX_set_signature() specifies the siglen bytes long signature sig to be verified against by EVP_PKEY_verify_final(). It must be used together with EVP_PKEY_verify_update() and EVP_PKEY_verify_final(). See \"NOTES\" below for a deeper explanation.

EVP_PKEY_verify_update() adds inlen bytes from in to the data to be processed for verification. The signature algorithm specification and implementation determine how the input bytes are processed and if there's a limit on the total size of the input. See \"NOTES\" below for a deeper explanation.

EVP_PKEY_verify_final() verifies the processed data, given only ctx. The signature to verify against must have been given with EVP_PKEY_CTX_set_signature().

EVP_PKEY_verify() is a one-shot function that performs the same thing as EVP_PKEY_CTX_set_signature() call with sig and siglen as parameters, followed by a single EVP_PKEY_verify_update() call with tbs and tbslen, followed by EVP_PKEY_verify_final() call.

"},{"location":"man3/EVP_PKEY_verify/#notes","title":"NOTES","text":""},{"location":"man3/EVP_PKEY_verify/#general","title":"General","text":"

Some signature implementations only accumulate the input data and do no further processing before verifying it (they expect the input to be a digest), while others compress the data, typically by internally producing a digest, and signing the result, which is then verified against a given signature. Some of them support both modes of operation at the same time. The caller is expected to know how the chosen algorithm is supposed to behave and under what conditions.

For example, an RSA implementation can be expected to only expect a digest as input, while ED25519 can be expected to process the input with a hash, i.e. to produce the digest internally, and while RSA-SHA256 can be expected to handle either mode of operation, depending on if the operation was initialized with EVP_PKEY_verify_init_ex2() or with EVP_PKEY_verify_message_init().

Similarly, an RSA implementation usually expects additional details to be set, like the message digest algorithm that the input is supposed to be digested with, as well as the padding mode (see EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_padding(3) and similar others), while an RSA-SHA256 implementation usually has these details pre-set and immutable.

The functions described here can't be used to combine separate algorithms. In particular, neither EVP_PKEY_CTX_set_signature_md(3) nor the OSSL_PARAM parameter \"digest\" (OSSL_SIGNATURE_PARAM_DIGEST) can be used to combine a signature algorithm with a hash algorithm to process the input. In other words, it's not possible to specify a ctx pre-loaded with an RSA pkey, or an algo that fetched RSA and try to specify SHA256 separately to get the functionality of RSA-SHA256. If combining algorithms in that manner is desired, please use EVP_DigestVerifyInit(3) and associated functions, or EVP_VerifyInit(3) and associated functions.

"},{"location":"man3/EVP_PKEY_verify/#performing-multiple-verifications","title":"Performing multiple verifications","text":"

When initialized using EVP_PKEY_verify_init_ex() or EVP_PKEY_verify_init_ex2(), EVP_PKEY_verify() can be called more than once on the same context to have several one-shot operations performed using the same parameters.

When initialized using EVP_PKEY_verify_message_init(), it's not possible to call EVP_PKEY_verify() multiple times.

"},{"location":"man3/EVP_PKEY_verify/#on-evp_pkey_ctx_set_signature","title":"On EVP_PKEY_CTX_set_signature()","text":"

Some signature algorithms (such as LMS) require the signature verification data be specified before verifying the message. Other algorithms allow the signature to be specified late. To allow either way (which may depend on the application's flow of input), the signature to be verified against must be specified using this function when using EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final() to perform the verification.

"},{"location":"man3/EVP_PKEY_verify/#return-values","title":"RETURN VALUES","text":"

All functions return 1 for success and 0 or a negative value for failure. However, unlike other functions, the return value 0 from EVP_PKEY_verify(), EVP_PKEY_verify_recover() and EVP_PKEY_verify_message_final() only indicates that the signature did not verify successfully (that is tbs did not match the original data or the signature was of invalid form) it is not an indication of a more serious error.

A negative value indicates an error other that signature verification failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_verify/#examples","title":"EXAMPLES","text":""},{"location":"man3/EVP_PKEY_verify/#rsa-with-pkcs1-padding-for-sha256","title":"RSA with PKCS#1 padding for SHA256","text":"

Verify signature using PKCS#1 padding and a SHA256 digest as input:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nunsigned char *md, *sig;\nsize_t mdlen, siglen;\nEVP_PKEY *verify_key;\n\n/*\n * NB: assumes verify_key, sig, siglen md and mdlen are already set up\n * and that verify_key is an RSA public key\n */\nctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);\nif (ctx == NULL)\n    /* Error occurred */\nif (EVP_PKEY_verify_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)\n    /* Error */\n\n/* Perform operation */\nret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);\n\n/*\n * ret == 1 indicates success, 0 verify failure and < 0 for some\n * other error.\n */\n
"},{"location":"man3/EVP_PKEY_verify/#rsa-sha256-with-a-pre-computed-digest","title":"RSA-SHA256 with a pre-computed digest","text":"

Verify a digest with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of sha256WithRSAEncryption, for which the padding is pre-determined to be RSA_PKCS1_PADDING, and the input digest is assumed to have been computed using SHA256.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* md is a SHA-256 digest in this example. */\nunsigned char *md, *sig;\nsize_t mdlen = 32, siglen;\nEVP_PKEY *signing_key;\n\n/*\n * NB: assumes verify_key, sig, siglen, md and mdlen are already set up\n * and that verify_key is an RSA public key\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL)\n    /* Error occurred */\nif (EVP_PKEY_verify_init_ex2(ctx, alg, NULL) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_verify(ctx, sig, siglen, md, mdlen) <= 0)\n    /* Error or signature doesn't verify */\n\n/* Perform operation */\nret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);\n\n/*\n * ret == 1 indicates success, 0 verify failure and < 0 for some\n * other error.\n */\n
"},{"location":"man3/EVP_PKEY_verify/#rsa-sha256-one-shot","title":"RSA-SHA256, one-shot","text":"

Verify a document with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of sha256WithRSAEncryption, for which the padding is pre-determined to be RSA_PKCS1_PADDING.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* in the input in this example. */\nunsigned char *in, *sig;\n/* inlen is the length of the input in this example. */\nsize_t inlen, siglen;\nEVP_PKEY *signing_key;\nEVP_SIGNATURE *alg;\n\n/*\n * NB: assumes signing_key, in and inlen are set up before\n * the next step. signing_key must be an RSA private key,\n * in must point to data to be digested and signed, and\n * inlen must be the size of the data in bytes.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL || alg == NULL)\n    /* Error occurred */\nif (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)\n    /* Error */\n\n/* Perform operation */\nret = EVP_PKEY_verify(ctx, sig, siglen, in, inlen);\n\n/*\n * ret == 1 indicates success, 0 verify failure and < 0 for some\n * other error.\n */\n
"},{"location":"man3/EVP_PKEY_verify/#rsa-sha256-using-update-and-final","title":"RSA-SHA256, using update and final","text":"

This is the same as the previous example, but allowing stream-like functionality.

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\n/* in is the input in this example. */\nunsigned char *in, *sig;\n/* inlen is the length of the input in this example. */\nsize_t inlen, siglen;\nEVP_PKEY *signing_key;\nEVP_SIGNATURE *alg;\n\n/*\n * NB: assumes signing_key, in and inlen are set up before\n * the next step. signing_key must be an RSA private key,\n * in must point to data to be digested and signed, and\n * inlen must be the size of the data in bytes.\n */\nctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);\nalg = EVP_SIGNATURE_fetch(NULL, \"RSA-SHA256\", NULL);\n\nif (ctx == NULL || alg == NULL)\n    /* Error occurred */\nif (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)\n    /* Error */\n\n/* We have the signature, specify it early */\nEVP_PKEY_CTX_set_signature(ctx, sig, siglen);\n\n/* Perform operation */\nwhile (inlen > 0) {\n    if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0)\n        /* Error */\n    if (inlen > 256) {\n        inlen -= 256;\n        in += 256;\n    } else {\n        inlen = 0;\n    }\n}\nret = EVP_PKEY_verify_message_final(ctx);\n\n/*\n * ret == 1 indicates success, 0 verify failure and < 0 for some\n * other error.\n */\n
"},{"location":"man3/EVP_PKEY_verify/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_verify/#history","title":"HISTORY","text":"

The EVP_PKEY_verify_init() and EVP_PKEY_verify() functions were added in OpenSSL 1.0.0.

The EVP_PKEY_verify_init_ex() function was added in OpenSSL 3.0.

The EVP_PKEY_verify_init_ex2(), EVP_PKEY_verify_message_init(), EVP_PKEY_verify_message_update(), EVP_PKEY_verify_message_final() and EVP_PKEY_CTX_set_signature() functions where added in OpenSSL 3.4.

"},{"location":"man3/EVP_PKEY_verify/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 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.

"},{"location":"man3/EVP_PKEY_verify_recover/","title":"EVP_PKEY_verify_recover","text":""},{"location":"man3/EVP_PKEY_verify_recover/#name","title":"NAME","text":"

EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover_init_ex, EVP_PKEY_verify_recover_init_ex2, EVP_PKEY_verify_recover - recover signature using a public key algorithm

"},{"location":"man3/EVP_PKEY_verify_recover/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);\nint EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx,\n                                    const OSSL_PARAM params[]);\nint EVP_PKEY_verify_recover_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,\n                                     const OSSL_PARAM params[]);\nint EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,\n                            unsigned char *rout, size_t *routlen,\n                            const unsigned char *sig, size_t siglen);\n
"},{"location":"man3/EVP_PKEY_verify_recover/#description","title":"DESCRIPTION","text":"

EVP_PKEY_verify_recover_init() initializes a public key algorithm context ctx for signing using the algorithm given when the context was created using EVP_PKEY_CTX_new(3) or variants thereof. The algorithm is used to fetch a EVP_SIGNATURE method implicitly, see \"Implicit fetch\" in provider(7) for more information about implicit fetches.

EVP_PKEY_verify_recover_init_ex() is the same as EVP_PKEY_verify_recover_init() but additionally sets the passed parameters params on the context before returning.

EVP_PKEY_verify_recover_init_ex2() is the same as EVP_PKEY_verify_recover_init_ex(), but works with an explicitly fetched EVP_SIGNATURE algo. A context ctx without a pre-loaded key cannot be used with this function. Depending on what algorithm was fetched, certain details revolving around the treatment of the input to EVP_PKEY_verify() may be pre-determined, and in that case, those details may normally not be changed. See \"NOTES\" below for a deeper explanation.

The EVP_PKEY_verify_recover() function recovers signed data using ctx. The signature is specified using the sig and siglen parameters. If rout is NULL then the maximum size of the output buffer is written to the routlen parameter. If rout is not NULL then before the call the routlen parameter should contain the length of the rout buffer, if the call is successful recovered data is written to rout and the amount of data written to routlen.

"},{"location":"man3/EVP_PKEY_verify_recover/#notes","title":"NOTES","text":"

Normally an application is only interested in whether a signature verification operation is successful in those cases the EVP_verify() function should be used.

Sometimes however it is useful to obtain the data originally signed using a signing operation. Only certain public key algorithms can recover a signature in this way (for example RSA in PKCS padding mode).

After the call to EVP_PKEY_verify_recover_init() algorithm specific control operations can be performed to set any appropriate parameters for the operation.

After the call to EVP_PKEY_verify_recover_init_ex2(), algorithm specific control operations may not be needed if the chosen algorithm implies that those controls pre-set (and immutable).

The function EVP_PKEY_verify_recover() can be called more than once on the same context if several operations are performed using the same parameters.

"},{"location":"man3/EVP_PKEY_verify_recover/#return-values","title":"RETURN VALUES","text":"

EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

"},{"location":"man3/EVP_PKEY_verify_recover/#examples","title":"EXAMPLES","text":"

Recover digest originally signed using PKCS#1 and SHA256 digest:

#include <openssl/evp.h>\n#include <openssl/rsa.h>\n\nEVP_PKEY_CTX *ctx;\nunsigned char *rout, *sig;\nsize_t routlen, siglen;\nEVP_PKEY *verify_key;\n\n/*\n * NB: assumes verify_key, sig and siglen are already set up\n * and that verify_key is an RSA public key\n */\nctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);\nif (!ctx)\n    /* Error occurred */\nif (EVP_PKEY_verify_recover_init(ctx) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)\n    /* Error */\nif (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)\n    /* Error */\n\n/* Determine buffer length */\nif (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)\n    /* Error */\n\nrout = OPENSSL_malloc(routlen);\n\nif (!rout)\n    /* malloc failure */\n\nif (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)\n    /* Error */\n\n/* Recovered data is routlen bytes written to buffer rout */\n
"},{"location":"man3/EVP_PKEY_verify_recover/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_derive(3)

"},{"location":"man3/EVP_PKEY_verify_recover/#history","title":"HISTORY","text":"

The EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() functions were added in OpenSSL 1.0.0.

The EVP_PKEY_verify_recover_init_ex() function was added in OpenSSL 3.0.

"},{"location":"man3/EVP_PKEY_verify_recover/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2024 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.

"},{"location":"man3/EVP_RAND/","title":"EVP_RAND","text":""},{"location":"man3/EVP_RAND/#name","title":"NAME","text":"

EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate, EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength, EVP_RAND_get_state, EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a, EVP_RAND_get0_name, EVP_RAND_names_do_all, EVP_RAND_get0_description, EVP_RAND_CTX_get_params, EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, EVP_RAND_STATE_ERROR - EVP RAND routines

"},{"location":"man3/EVP_RAND/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef struct evp_rand_st EVP_RAND;\ntypedef struct evp_rand_ctx_st EVP_RAND_CTX;\n\nEVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,\n                       const char *properties);\nint EVP_RAND_up_ref(EVP_RAND *rand);\nvoid EVP_RAND_free(EVP_RAND *rand);\nEVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);\nvoid EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);\nint EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx);\nEVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx);\nint EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);\nint EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);\nint EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);\nconst OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);\nconst OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);\nconst OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx);\nconst OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx);\nconst char *EVP_RAND_get0_name(const EVP_RAND *rand);\nconst char *EVP_RAND_get0_description(const EVP_RAND *rand);\nint EVP_RAND_is_a(const EVP_RAND *rand, const char *name);\nconst OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand);\nvoid EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,\n                              void (*fn)(EVP_RAND *rand, void *arg),\n                              void *arg);\nint EVP_RAND_names_do_all(const EVP_RAND *rand,\n                          void (*fn)(const char *name, void *data),\n                          void *data);\n\nint EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,\n                         int prediction_resistance,\n                         const unsigned char *pstr, size_t pstr_len,\n                         const OSSL_PARAM params[]);\nint EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);\nint EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,\n                      unsigned int strength, int prediction_resistance,\n                      const unsigned char *addin, size_t addin_len);\nint EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,\n                    const unsigned char *ent, size_t ent_len,\n                    const unsigned char *addin, size_t addin_len);\nint EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);\nint EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);\nint EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);\nunsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx);\nint EVP_RAND_get_state(EVP_RAND_CTX *ctx);\n\n#define EVP_RAND_STATE_UNINITIALISED    0\n#define EVP_RAND_STATE_READY            1\n#define EVP_RAND_STATE_ERROR            2\n
"},{"location":"man3/EVP_RAND/#description","title":"DESCRIPTION","text":"

The EVP RAND routines are a high-level interface to random number generators both deterministic and not. If you just want to generate random bytes then you don't need to use these functions: just call RAND_bytes() or RAND_priv_bytes(). If you want to do more, these calls should be used instead of the older RAND and RAND_DRBG functions.

After creating a EVP_RAND_CTX for the required algorithm using EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_RAND_instantiate() call or using calls to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, call EVP_RAND_generate() to produce cryptographically secure random bytes.

"},{"location":"man3/EVP_RAND/#types","title":"Types","text":"

EVP_RAND is a type that holds the implementation of a RAND.

EVP_RAND_CTX is a context type that holds the algorithm inputs. EVP_RAND_CTX structures are reference counted.

"},{"location":"man3/EVP_RAND/#algorithm-implementation-fetching","title":"Algorithm implementation fetching","text":"

EVP_RAND_fetch() fetches an implementation of a RAND algorithm, given a library context libctx and a set of properties. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_RAND_free(3).

EVP_RAND_up_ref() increments the reference count of an already fetched RAND.

EVP_RAND_free() frees a fetched algorithm. NULL is a valid parameter, for which this function is a no-op.

"},{"location":"man3/EVP_RAND/#context-manipulation-functions","title":"Context manipulation functions","text":"

EVP_RAND_CTX_new() creates a new context for the RAND implementation rand. If not NULL, parent specifies the seed source for this implementation. Not all random number generators need to have a seed source specified. If a parent is required, a NULL parent will utilise the operating system entropy sources. It is recommended to minimise the number of random number generators that rely on the operating system for their randomness because this is often scarce.

EVP_RAND_CTX_free() frees up the context ctx. If ctx is NULL, nothing is done.

EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the context ctx.

"},{"location":"man3/EVP_RAND/#random-number-generator-functions","title":"Random Number Generator Functions","text":"

EVP_RAND_instantiate() processes any parameters in params and then instantiates the RAND ctx with a minimum security strength of <strength> and personalisation string pstr of length <pstr_len>. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_uninstantiate() uninstantiates the RAND ctx as per NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot be used to generate bytes. It can only be freed or instantiated again.

EVP_RAND_generate() produces random bytes from the RAND ctx with the additional input addin of length addin_len. The bytes produced will meet the security strength. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_reseed() reseeds the RAND with new entropy. Entropy ent of length ent_len bytes can be supplied as can additional input addin of length addin_len bytes. In the FIPS provider, both are treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. Additional seed material is also drawn from the RAND's parent or the operating system. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes from the RAND ctx. The function returns the length of the generated nonce. If out is NULL, the length is still returned but no generation takes place. This allows a caller to dynamically allocate a buffer of the appropriate size.

EVP_RAND_enable_locking() enables locking for the RAND ctx and all of its parents. After this ctx will operate in a thread safe manner, albeit more slowly. This function is not itself thread safe if called with the same ctx from multiple threads. Typically locking should be enabled before a ctx is shared across multiple threads.

EVP_RAND_get_params() retrieves details about the implementation rand. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.

EVP_RAND_gettable_params() returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. EVP_RAND_gettable_params() returns parameters that can be used with EVP_RAND_get_params().

EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.

EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

"},{"location":"man3/EVP_RAND/#information-functions","title":"Information functions","text":"

EVP_RAND_get_strength() returns the security strength of the RAND ctx.

EVP_RAND_get_state() returns the current state of the RAND ctx. States defined by the OpenSSL RNGs are:

EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_RAND_get0_provider() returns the provider that holds the implementation of the given rand.

EVP_RAND_do_all_provided() traverses all RAND implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_RAND_get0_name() returns the canonical name of rand.

EVP_RAND_names_do_all() traverses all names for rand, and calls fn with each name and data.

EVP_RAND_get0_description() returns a description of the rand, meant for display and human consumption. The description is at the discretion of the rand implementation.

EVP_RAND_verify_zeroization() confirms if the internal DRBG state is currently zeroed. This is used by the FIPS provider to support the mandatory self tests.

"},{"location":"man3/EVP_RAND/#parameters","title":"PARAMETERS","text":"

The standard parameter names are:

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:

"},{"location":"man3/EVP_RAND/#notes","title":"NOTES","text":"

The use of a nonzero value for the prediction_resistance argument to EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should be used sparingly. In the default setup, this will cause all public and private DRBGs to be reseeded on next use. Since, by default, public and private DRBGs are allocated on a per thread basis, this can result in significant overhead for highly multi-threaded applications. For normal use-cases, the default \"reseed_requests\" and \"reseed_time_interval\" thresholds ensure sufficient prediction resistance over time and you can reduce those values if you think they are too high. Explicitly requesting prediction resistance is intended for more special use-cases like generating long-term secrets.

An EVP_RAND_CTX needs to have locking enabled if it acts as the parent of more than one child and the children can be accessed concurrently. This must be done by explicitly calling EVP_RAND_enable_locking().

The RAND life-cycle is described in life_cycle-rand(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

"},{"location":"man3/EVP_RAND/#return-values","title":"RETURN VALUES","text":"

EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL if allocation failed.

EVP_RAND_get0_provider() returns a pointer to the provider for the RAND, or NULL on error.

EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated with the context.

EVP_RAND_get0_name() returns the name of the random number generation algorithm.

EVP_RAND_up_ref() returns 1 on success, 0 on error.

EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX structure or NULL if an error occurred.

EVP_RAND_CTX_free() does not return a value.

EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error.

EVP_RAND_nonce() returns the length of the nonce.

EVP_RAND_get_strength() returns the strength of the random number generator in bits.

EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.

EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is currently zeroed, and 0 if not.

The remaining functions return 1 for success and 0 or a negative value for failure.

"},{"location":"man3/EVP_RAND/#see-also","title":"SEE ALSO","text":"

RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7), EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7), life_cycle-rand(7)

"},{"location":"man3/EVP_RAND/#history","title":"HISTORY","text":"

EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1.

The remaining functions were added in OpenSSL 3.0.

"},{"location":"man3/EVP_RAND/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2024 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.

"},{"location":"man3/EVP_SIGNATURE/","title":"EVP_SIGNATURE","text":""},{"location":"man3/EVP_SIGNATURE/#name","title":"NAME","text":"

EVP_SIGNATURE, EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref, EVP_SIGNATURE_is_a, EVP_SIGNATURE_get0_provider, EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all, EVP_SIGNATURE_get0_name, EVP_SIGNATURE_get0_description, EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params - Functions to manage EVP_SIGNATURE algorithm objects

"},{"location":"man3/EVP_SIGNATURE/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\ntypedef struct evp_signature_st EVP_SIGNATURE;\n\nEVP_SIGNATURE *EVP_SIGNATURE_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                                   const char *properties);\nvoid EVP_SIGNATURE_free(EVP_SIGNATURE *signature);\nint EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);\nconst char *EVP_SIGNATURE_get0_name(const EVP_SIGNATURE *signature);\nint EVP_SIGNATURE_is_a(const EVP_SIGNATURE *signature, const char *name);\nOSSL_PROVIDER *EVP_SIGNATURE_get0_provider(const EVP_SIGNATURE *signature);\nvoid EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx,\n                                   void (*fn)(EVP_SIGNATURE *signature,\n                                              void *arg),\n                                   void *arg);\nint EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature,\n                               void (*fn)(const char *name, void *data),\n                               void *data);\nconst char *EVP_SIGNATURE_get0_name(const EVP_SIGNATURE *signature);\nconst char *EVP_SIGNATURE_get0_description(const EVP_SIGNATURE *signature);\nconst OSSL_PARAM *EVP_SIGNATURE_gettable_ctx_params(const EVP_SIGNATURE *sig);\nconst OSSL_PARAM *EVP_SIGNATURE_settable_ctx_params(const EVP_SIGNATURE *sig);\n
"},{"location":"man3/EVP_SIGNATURE/#description","title":"DESCRIPTION","text":"

EVP_SIGNATURE_fetch() fetches the implementation for the given algorithm from any provider offering it, within the criteria given by the properties. The algorithm will be one offering functions for performing signature related tasks such as signing and verifying. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_SIGNATURE_free().

EVP_SIGNATURE_free() decrements the reference count for the EVP_SIGNATURE structure. Typically this structure will have been obtained from an earlier call to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_SIGNATURE_up_ref() increments the reference count for an EVP_SIGNATURE structure.

EVP_SIGNATURE_is_a() returns 1 if signature is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_SIGNATURE_get0_provider() returns the provider that signature was fetched from.

EVP_SIGNATURE_do_all_provided() traverses all SIGNATURE implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_SIGNATURE_get0_name() returns the algorithm name from the provided implementation for the given signature. Note that the signature may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the signature object and should not be freed by the caller.

EVP_SIGNATURE_names_do_all() traverses all names for signature, and calls fn with each name and data.

EVP_SIGNATURE_get0_description() returns a description of the signature, meant for display and human consumption. The description is at the discretion of the signature implementation.

EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set by a signature algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_SIGNATURE/#return-values","title":"RETURN VALUES","text":"

EVP_SIGNATURE_fetch() returns a pointer to an EVP_SIGNATURE for success or NULL for failure.

EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise.

EVP_SIGNATURE_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_SIGNATURE/#see-also","title":"SEE ALSO","text":"

\"ALGORITHM FETCHING\" in crypto(7), OSSL_PROVIDER(3)

"},{"location":"man3/EVP_SIGNATURE/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_SIGNATURE/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2024 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.

"},{"location":"man3/EVP_SealInit/","title":"EVP_SealInit","text":""},{"location":"man3/EVP_SealInit/#name","title":"NAME","text":"

EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption

"},{"location":"man3/EVP_SealInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,\n                 unsigned char **ek, int *ekl, unsigned char *iv,\n                 EVP_PKEY **pubk, int npubk);\nint EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,\n                   int *outl, unsigned char *in, int inl);\nint EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);\n
"},{"location":"man3/EVP_SealInit/#description","title":"DESCRIPTION","text":"

The EVP envelope routines are a high-level interface to envelope encryption. They generate a random key and IV (if required) then \"envelope\" it by using public key encryption. Data can then be encrypted using this key.

EVP_SealInit() initializes a cipher context ctx for encryption with cipher type using a random secret key and IV. type is normally supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted using one or more public keys, this allows the same encrypted data to be decrypted using any of the corresponding private keys. ek is an array of buffers where the public key encrypted secret key will be written, each buffer must contain enough room for the corresponding encrypted key: that is ek[i] must have room for EVP_PKEY_get_size(pubk[i]) bytes. The actual size of each encrypted secret key is written to the array ekl. pubk is an array of npubk public keys.

The iv parameter is a buffer where the generated IV is written to. It must contain enough room for the corresponding cipher's IV, as determined by (for example) EVP_CIPHER_get_iv_length(type).

If the cipher does not require an IV then the iv parameter is ignored and can be NULL.

EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as documented on the EVP_EncryptInit(3) manual page.

"},{"location":"man3/EVP_SealInit/#return-values","title":"RETURN VALUES","text":"

EVP_SealInit() returns 0 on error or npubk if successful.

EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for failure.

"},{"location":"man3/EVP_SealInit/#notes","title":"NOTES","text":"

Because a random secret key is generated the random number generator must be seeded when EVP_SealInit() is called. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

The public key must be RSA because it is the only OpenSSL public key algorithm that supports key transport.

Envelope encryption is the usual method of using public key encryption on large amounts of data, this is because public key encryption is slow but symmetric encryption is fast. So symmetric encryption is used for bulk encryption and the small random symmetric key used is transferred using public key encryption.

It is possible to call EVP_SealInit() twice in the same way as EVP_EncryptInit(). The first call should have npubk set to 0 and (after setting any cipher parameters) it should be called again with type set to NULL.

"},{"location":"man3/EVP_SealInit/#see-also","title":"SEE ALSO","text":"

evp(7), RAND_bytes(3), EVP_EncryptInit(3), EVP_OpenInit(3), RAND(7)

"},{"location":"man3/EVP_SealInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 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.

"},{"location":"man3/EVP_SignInit/","title":"EVP_SignInit","text":""},{"location":"man3/EVP_SignInit/#name","title":"NAME","text":"

EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal_ex, EVP_SignFinal - EVP signing functions

"},{"location":"man3/EVP_SignInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);\nint EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);\nint EVP_SignFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s,\n                     EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, const char *propq);\nint EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s,\n                  EVP_PKEY *pkey);\n\nvoid EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);\n
"},{"location":"man3/EVP_SignInit/#description","title":"DESCRIPTION","text":"

The EVP signature routines are a high-level interface to digital signatures.

EVP_SignInit_ex() sets up signing context ctx to use digest type from ENGINE impl. ctx must be created with EVP_MD_CTX_new() before calling this function.

EVP_SignUpdate() hashes cnt bytes of data at d into the signature context ctx. This function can be called several times on the same ctx to include additional data.

EVP_SignFinal_ex() signs the data in ctx using the private key pkey and places the signature in sig. The library context libctx and property query propq are used when creating a context to use with the key pkey. sig must be at least EVP_PKEY_get_size(pkey) bytes in size. s is an OUT parameter, and not used as an IN parameter. The number of bytes of data written (i.e. the length of the signature) will be written to the integer at s, at most EVP_PKEY_get_size(pkey) bytes will be written.

EVP_SignFinal() is similar to EVP_SignFinal_ex() but uses default values of NULL for the library context libctx and the property query propq.

EVP_SignInit() initializes a signing context ctx to use the default implementation of digest type.

"},{"location":"man3/EVP_SignInit/#return-values","title":"RETURN VALUES","text":"

EVP_SignInit_ex(), EVP_SignUpdate(), EVP_SignFinal_ex() and EVP_SignFinal() return 1 for success and 0 for failure.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/EVP_SignInit/#notes","title":"NOTES","text":"

The EVP interface to digital signatures should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible.

When signing with some private key types the random number generator must be seeded. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

The call to EVP_SignFinal() internally finalizes a copy of the digest context. This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called later to digest and sign additional data.cApplications may disable this behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via EVP_MD_CTX_set_flags(3).

Since only a copy of the digest context is ever finalized the context must be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak will occur.

Note that not all providers support continuation, in case the selected provider does not allow to duplicate contexts EVP_SignFinal() will finalize the digest context and attempting to process additional data via EVP_SignUpdate() will result in an error.

"},{"location":"man3/EVP_SignInit/#bugs","title":"BUGS","text":"

Older versions of this documentation wrongly stated that calls to EVP_SignUpdate() could not be made after calling EVP_SignFinal().

Since the private key is passed in the call to EVP_SignFinal() any error relating to the private key (for example an unsuitable key and digest combination) will not be indicated until after potentially large amounts of data have been passed through EVP_SignUpdate().

It is not possible to change the signing parameters using these function.

The previous two bugs are fixed in the newer EVP_DigestSign*() functions.

"},{"location":"man3/EVP_SignInit/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_size(3), EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3), EVP_VerifyInit(3), EVP_DigestInit(3), evp(7), HMAC(3), MD2(3), MD5(3), MDC2(3), RIPEMD160(3), SHA1(3), openssl-dgst(1)

"},{"location":"man3/EVP_SignInit/#history","title":"HISTORY","text":"

The function EVP_SignFinal_ex() was added in OpenSSL 3.0.

"},{"location":"man3/EVP_SignInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/EVP_VerifyInit/","title":"EVP_VerifyInit","text":""},{"location":"man3/EVP_VerifyInit/#name","title":"NAME","text":"

EVP_VerifyInit_ex, EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal_ex, EVP_VerifyFinal - EVP signature verification functions

"},{"location":"man3/EVP_VerifyInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);\nint EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);\nint EVP_VerifyFinal_ex(EVP_MD_CTX *ctx, const unsigned char *sigbuf,\n                       unsigned int siglen, EVP_PKEY *pkey,\n                       OSSL_LIB_CTX *libctx, const char *propq);\nint EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen,\n                    EVP_PKEY *pkey);\n\nint EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);\n
"},{"location":"man3/EVP_VerifyInit/#description","title":"DESCRIPTION","text":"

The EVP signature verification routines are a high-level interface to digital signatures.

EVP_VerifyInit_ex() sets up verification context ctx to use digest type from ENGINE impl. ctx must be created by calling EVP_MD_CTX_new() before calling this function.

EVP_VerifyUpdate() hashes cnt bytes of data at d into the verification context ctx. This function can be called several times on the same ctx to include additional data.

EVP_VerifyFinal_ex() verifies the data in ctx using the public key pkey and siglen bytes in sigbuf. The library context libctx and property query propq are used when creating a context to use with the key pkey.

EVP_VerifyFinal() is similar to EVP_VerifyFinal_ex() but uses default values of NULL for the library context libctx and the property query propq.

EVP_VerifyInit() initializes verification context ctx to use the default implementation of digest type.

"},{"location":"man3/EVP_VerifyInit/#return-values","title":"RETURN VALUES","text":"

EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for failure.

EVP_VerifyFinal_ex() and EVP_VerifyFinal() return 1 for a correct signature, 0 for failure and a negative value if some other error occurred.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/EVP_VerifyInit/#notes","title":"NOTES","text":"

The EVP interface to digital signatures should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible.

The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data. Applications may disable this behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via EVP_MD_CTX_set_flags(3).

Since only a copy of the digest context is ever finalized the context must be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak will occur.

Note that not all providers support continuation, in case the selected provider does not allow to duplicate contexts EVP_VerifyFinal() will finalize the digest context and attempting to process additional data via EVP_VerifyUpdate() will result in an error.

"},{"location":"man3/EVP_VerifyInit/#bugs","title":"BUGS","text":"

Older versions of this documentation wrongly stated that calls to EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().

Since the public key is passed in the call to EVP_SignFinal() any error relating to the private key (for example an unsuitable key and digest combination) will not be indicated until after potentially large amounts of data have been passed through EVP_SignUpdate().

It is not possible to change the signing parameters using these function.

The previous two bugs are fixed in the newer EVP_DigestVerify*() function.

"},{"location":"man3/EVP_VerifyInit/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_SignInit(3), EVP_DigestInit(3), evp(7), HMAC(3), MD2(3), MD5(3), MDC2(3), RIPEMD160(3), SHA1(3), openssl-dgst(1)

"},{"location":"man3/EVP_VerifyInit/#history","title":"HISTORY","text":"

The function EVP_VerifyFinal_ex() was added in OpenSSL 3.0.

"},{"location":"man3/EVP_VerifyInit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 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.

"},{"location":"man3/EVP_aes_128_gcm/","title":"EVP_aes_128_gcm","text":""},{"location":"man3/EVP_aes_128_gcm/#name","title":"NAME","text":"

EVP_aes_128_cbc, EVP_aes_192_cbc, EVP_aes_256_cbc, EVP_aes_128_cfb, EVP_aes_192_cfb, EVP_aes_256_cfb, EVP_aes_128_cfb1, EVP_aes_192_cfb1, EVP_aes_256_cfb1, EVP_aes_128_cfb8, EVP_aes_192_cfb8, EVP_aes_256_cfb8, EVP_aes_128_cfb128, EVP_aes_192_cfb128, EVP_aes_256_cfb128, EVP_aes_128_ctr, EVP_aes_192_ctr, EVP_aes_256_ctr, EVP_aes_128_ecb, EVP_aes_192_ecb, EVP_aes_256_ecb, EVP_aes_128_ofb, EVP_aes_192_ofb, EVP_aes_256_ofb, EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1, EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256, EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ocb, EVP_aes_192_ocb, EVP_aes_256_ocb, EVP_aes_128_wrap, EVP_aes_192_wrap, EVP_aes_256_wrap, EVP_aes_128_wrap_pad, EVP_aes_192_wrap_pad, EVP_aes_256_wrap_pad, EVP_aes_128_xts, EVP_aes_256_xts - EVP AES cipher

"},{"location":"man3/EVP_aes_128_gcm/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_ciphername(void)\n

EVP_ciphername is used a placeholder for any of the described cipher functions, such as EVP_aes_128_cbc.

"},{"location":"man3/EVP_aes_128_gcm/#description","title":"DESCRIPTION","text":"

The AES encryption algorithm for EVP.

"},{"location":"man3/EVP_aes_128_gcm/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-AES(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_aes_128_gcm/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_aes_128_gcm/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_aes_128_gcm/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_aria_128_gcm/","title":"EVP_aria_128_gcm","text":""},{"location":"man3/EVP_aria_128_gcm/#name","title":"NAME","text":"

EVP_aria_128_cbc, EVP_aria_192_cbc, EVP_aria_256_cbc, EVP_aria_128_cfb, EVP_aria_192_cfb, EVP_aria_256_cfb, EVP_aria_128_cfb1, EVP_aria_192_cfb1, EVP_aria_256_cfb1, EVP_aria_128_cfb8, EVP_aria_192_cfb8, EVP_aria_256_cfb8, EVP_aria_128_cfb128, EVP_aria_192_cfb128, EVP_aria_256_cfb128, EVP_aria_128_ctr, EVP_aria_192_ctr, EVP_aria_256_ctr, EVP_aria_128_ecb, EVP_aria_192_ecb, EVP_aria_256_ecb, EVP_aria_128_ofb, EVP_aria_192_ofb, EVP_aria_256_ofb, EVP_aria_128_ccm, EVP_aria_192_ccm, EVP_aria_256_ccm, EVP_aria_128_gcm, EVP_aria_192_gcm, EVP_aria_256_gcm, - EVP ARIA cipher

"},{"location":"man3/EVP_aria_128_gcm/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_ciphername(void)\n

EVP_ciphername is used a placeholder for any of the described cipher functions, such as EVP_aria_128_cbc.

"},{"location":"man3/EVP_aria_128_gcm/#description","title":"DESCRIPTION","text":"

The ARIA encryption algorithm for EVP.

"},{"location":"man3/EVP_aria_128_gcm/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-ARIA(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_aria_128_gcm/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_aria_128_gcm/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_aria_128_gcm/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_bf_cbc/","title":"EVP_bf_cbc","text":""},{"location":"man3/EVP_bf_cbc/#name","title":"NAME","text":"

EVP_bf_cbc, EVP_bf_cfb, EVP_bf_cfb64, EVP_bf_ecb, EVP_bf_ofb - EVP Blowfish cipher

"},{"location":"man3/EVP_bf_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_bf_cbc(void);\nconst EVP_CIPHER *EVP_bf_cfb(void);\nconst EVP_CIPHER *EVP_bf_cfb64(void);\nconst EVP_CIPHER *EVP_bf_ecb(void);\nconst EVP_CIPHER *EVP_bf_ofb(void);\n
"},{"location":"man3/EVP_bf_cbc/#description","title":"DESCRIPTION","text":"

The Blowfish encryption algorithm for EVP.

This is a variable key length cipher.

"},{"location":"man3/EVP_bf_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-BLOWFISH(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_bf_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_bf_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_bf_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_blake2b512/","title":"EVP_blake2b512","text":""},{"location":"man3/EVP_blake2b512/#name","title":"NAME","text":"

EVP_blake2b512, EVP_blake2s256 - BLAKE2 For EVP

"},{"location":"man3/EVP_blake2b512/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_blake2b512(void);\nconst EVP_MD *EVP_blake2s256(void);\n
"},{"location":"man3/EVP_blake2b512/#description","title":"DESCRIPTION","text":"

BLAKE2 is an improved version of BLAKE, which was submitted to the NIST SHA-3 algorithm competition. The BLAKE2s and BLAKE2b algorithms are described in RFC 7693.

"},{"location":"man3/EVP_blake2b512/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-BLAKE2(7) instead. See \"Performance\" in crypto(7) for further information.

Both algorithms support a variable-length digest, but this is only available through EVP_MD-BLAKE2(7).

"},{"location":"man3/EVP_blake2b512/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_blake2b512/#conforming-to","title":"CONFORMING TO","text":"

RFC 7693.

"},{"location":"man3/EVP_blake2b512/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_blake2b512/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_camellia_128_ecb/","title":"EVP_camellia_128_ecb","text":""},{"location":"man3/EVP_camellia_128_ecb/#name","title":"NAME","text":"

EVP_camellia_128_cbc, EVP_camellia_192_cbc, EVP_camellia_256_cbc, EVP_camellia_128_cfb, EVP_camellia_192_cfb, EVP_camellia_256_cfb, EVP_camellia_128_cfb1, EVP_camellia_192_cfb1, EVP_camellia_256_cfb1, EVP_camellia_128_cfb8, EVP_camellia_192_cfb8, EVP_camellia_256_cfb8, EVP_camellia_128_cfb128, EVP_camellia_192_cfb128, EVP_camellia_256_cfb128, EVP_camellia_128_ctr, EVP_camellia_192_ctr, EVP_camellia_256_ctr, EVP_camellia_128_ecb, EVP_camellia_192_ecb, EVP_camellia_256_ecb, EVP_camellia_128_ofb, EVP_camellia_192_ofb, EVP_camellia_256_ofb - EVP Camellia cipher

"},{"location":"man3/EVP_camellia_128_ecb/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_ciphername(void)\n

EVP_ciphername is used a placeholder for any of the described cipher functions, such as EVP_camellia_128_cbc.

"},{"location":"man3/EVP_camellia_128_ecb/#description","title":"DESCRIPTION","text":"

The Camellia encryption algorithm for EVP.

"},{"location":"man3/EVP_camellia_128_ecb/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-CAMELLIA(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_camellia_128_ecb/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_camellia_128_ecb/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_camellia_128_ecb/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_cast5_cbc/","title":"EVP_cast5_cbc","text":""},{"location":"man3/EVP_cast5_cbc/#name","title":"NAME","text":"

EVP_cast5_cbc, EVP_cast5_cfb, EVP_cast5_cfb64, EVP_cast5_ecb, EVP_cast5_ofb - EVP CAST cipher

"},{"location":"man3/EVP_cast5_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_cast5_cbc(void);\nconst EVP_CIPHER *EVP_cast5_cfb(void);\nconst EVP_CIPHER *EVP_cast5_cfb64(void);\nconst EVP_CIPHER *EVP_cast5_ecb(void);\nconst EVP_CIPHER *EVP_cast5_ofb(void);\n
"},{"location":"man3/EVP_cast5_cbc/#description","title":"DESCRIPTION","text":"

The CAST encryption algorithm for EVP.

This is a variable key length cipher.

"},{"location":"man3/EVP_cast5_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-CAST(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_cast5_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_cast5_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_cast5_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_chacha20/","title":"EVP_chacha20","text":""},{"location":"man3/EVP_chacha20/#name","title":"NAME","text":"

EVP_chacha20, EVP_chacha20_poly1305 - EVP ChaCha20 stream cipher

"},{"location":"man3/EVP_chacha20/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_chacha20(void);\nconst EVP_CIPHER *EVP_chacha20_poly1305(void);\n
"},{"location":"man3/EVP_chacha20/#description","title":"DESCRIPTION","text":"

The ChaCha20 stream cipher for EVP.

"},{"location":"man3/EVP_chacha20/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-CHACHA(7) instead. See \"Performance\" in crypto(7) for further information.

RFC 7539 uses a 32 bit counter and a 96 bit nonce for the IV.

"},{"location":"man3/EVP_chacha20/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_chacha20/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_chacha20/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_des_cbc/","title":"EVP_des_cbc","text":""},{"location":"man3/EVP_des_cbc/#name","title":"NAME","text":"

EVP_des_cbc, EVP_des_cfb, EVP_des_cfb1, EVP_des_cfb8, EVP_des_cfb64, EVP_des_ecb, EVP_des_ofb, EVP_des_ede, EVP_des_ede_cbc, EVP_des_ede_cfb, EVP_des_ede_cfb64, EVP_des_ede_ecb, EVP_des_ede_ofb, EVP_des_ede3, EVP_des_ede3_cbc, EVP_des_ede3_cfb, EVP_des_ede3_cfb1, EVP_des_ede3_cfb8, EVP_des_ede3_cfb64, EVP_des_ede3_ecb, EVP_des_ede3_ofb, EVP_des_ede3_wrap - EVP DES cipher

"},{"location":"man3/EVP_des_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_ciphername(void)\n

EVP_ciphername is used a placeholder for any of the described cipher functions, such as EVP_des_cbc.

"},{"location":"man3/EVP_des_cbc/#description","title":"DESCRIPTION","text":"

The DES encryption algorithm for EVP.

"},{"location":"man3/EVP_des_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-DES(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_des_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_des_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_des_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_desx_cbc/","title":"EVP_desx_cbc","text":""},{"location":"man3/EVP_desx_cbc/#name","title":"NAME","text":"

EVP_desx_cbc - EVP DES-X cipher

"},{"location":"man3/EVP_desx_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_desx_cbc(void);\n
"},{"location":"man3/EVP_desx_cbc/#description","title":"DESCRIPTION","text":"

The DES-X encryption algorithm for EVP.

All modes below use a key length of 128 bits and acts on blocks of 128-bits.

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-DES(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_desx_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_desx_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_desx_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_idea_cbc/","title":"EVP_idea_cbc","text":""},{"location":"man3/EVP_idea_cbc/#name","title":"NAME","text":"

EVP_idea_cbc, EVP_idea_cfb, EVP_idea_cfb64, EVP_idea_ecb, EVP_idea_ofb - EVP IDEA cipher

"},{"location":"man3/EVP_idea_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_idea_cbc(void);\nconst EVP_CIPHER *EVP_idea_cfb(void);\nconst EVP_CIPHER *EVP_idea_cfb64(void);\nconst EVP_CIPHER *EVP_idea_ecb(void);\nconst EVP_CIPHER *EVP_idea_ofb(void);\n
"},{"location":"man3/EVP_idea_cbc/#description","title":"DESCRIPTION","text":"

The IDEA encryption algorithm for EVP.

"},{"location":"man3/EVP_idea_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-IDEA(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_idea_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_idea_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_idea_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_md2/","title":"EVP_md2","text":""},{"location":"man3/EVP_md2/#name","title":"NAME","text":"

EVP_md2 - MD2 For EVP

"},{"location":"man3/EVP_md2/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_md2(void);\n
"},{"location":"man3/EVP_md2/#description","title":"DESCRIPTION","text":"

MD2 is a cryptographic hash function standardized in RFC 1319 and designed by Ronald Rivest. This implementation is only available with the legacy provider.

"},{"location":"man3/EVP_md2/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-MD2(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_md2/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_md2/#conforming-to","title":"CONFORMING TO","text":"

IETF RFC 1319.

"},{"location":"man3/EVP_md2/#see-also","title":"SEE ALSO","text":"

evp(7), provider(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_md2/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_md4/","title":"EVP_md4","text":""},{"location":"man3/EVP_md4/#name","title":"NAME","text":"

EVP_md4 - MD4 For EVP

"},{"location":"man3/EVP_md4/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_md4(void);\n
"},{"location":"man3/EVP_md4/#description","title":"DESCRIPTION","text":"

MD4 is a cryptographic hash function standardized in RFC 1320 and designed by Ronald Rivest, first published in 1990. This implementation is only available with the legacy provider.

"},{"location":"man3/EVP_md4/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-MD4(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_md4/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_md4/#conforming-to","title":"CONFORMING TO","text":"

IETF RFC 1320.

"},{"location":"man3/EVP_md4/#see-also","title":"SEE ALSO","text":"

evp(7), provider(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_md4/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_md5/","title":"EVP_md5","text":""},{"location":"man3/EVP_md5/#name","title":"NAME","text":"

EVP_md5, EVP_md5_sha1 - MD5 For EVP

"},{"location":"man3/EVP_md5/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_md5(void);\nconst EVP_MD *EVP_md5_sha1(void);\n
"},{"location":"man3/EVP_md5/#description","title":"DESCRIPTION","text":"

MD5 is a cryptographic hash function standardized in RFC 1321 and designed by Ronald Rivest.

The CMU Software Engineering Institute considers MD5 unsuitable for further use since its security has been severely compromised.

"},{"location":"man3/EVP_md5/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-MD5(7) or EVP_MD-MD5-SHA1(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_md5/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_md5/#conforming-to","title":"CONFORMING TO","text":"

IETF RFC 1321.

"},{"location":"man3/EVP_md5/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_md5/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_mdc2/","title":"EVP_mdc2","text":""},{"location":"man3/EVP_mdc2/#name","title":"NAME","text":"

EVP_mdc2 - MDC-2 For EVP

"},{"location":"man3/EVP_mdc2/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_mdc2(void);\n
"},{"location":"man3/EVP_mdc2/#description","title":"DESCRIPTION","text":"

MDC-2 (Modification Detection Code 2 or Meyer-Schilling) is a cryptographic hash function based on a block cipher. This implementation is only available with the legacy provider.

"},{"location":"man3/EVP_mdc2/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-MDC2(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_mdc2/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_mdc2/#conforming-to","title":"CONFORMING TO","text":"

ISO/IEC 10118-2:2000 Hash-Function 2, with DES as the underlying block cipher.

"},{"location":"man3/EVP_mdc2/#see-also","title":"SEE ALSO","text":"

evp(7), provider(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_mdc2/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_rc2_cbc/","title":"EVP_rc2_cbc","text":""},{"location":"man3/EVP_rc2_cbc/#name","title":"NAME","text":"

EVP_rc2_cbc, EVP_rc2_cfb, EVP_rc2_cfb64, EVP_rc2_ecb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc - EVP RC2 cipher

"},{"location":"man3/EVP_rc2_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_rc2_cbc(void);\nconst EVP_CIPHER *EVP_rc2_cfb(void);\nconst EVP_CIPHER *EVP_rc2_cfb64(void);\nconst EVP_CIPHER *EVP_rc2_ecb(void);\nconst EVP_CIPHER *EVP_rc2_ofb(void);\nconst EVP_CIPHER *EVP_rc2_40_cbc(void);\nconst EVP_CIPHER *EVP_rc2_64_cbc(void);\n
"},{"location":"man3/EVP_rc2_cbc/#description","title":"DESCRIPTION","text":"

The RC2 encryption algorithm for EVP.

"},{"location":"man3/EVP_rc2_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-RC2(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_rc2_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_rc2_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_rc2_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_rc4/","title":"EVP_rc4","text":""},{"location":"man3/EVP_rc4/#name","title":"NAME","text":"

EVP_rc4, EVP_rc4_40, EVP_rc4_hmac_md5 - EVP RC4 stream cipher

"},{"location":"man3/EVP_rc4/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_rc4(void);\nconst EVP_CIPHER *EVP_rc4_40(void);\nconst EVP_CIPHER *EVP_rc4_hmac_md5(void);\n
"},{"location":"man3/EVP_rc4/#description","title":"DESCRIPTION","text":"

The RC4 stream cipher for EVP.

"},{"location":"man3/EVP_rc4/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-RC4(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_rc4/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_rc4/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_rc4/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_rc5_32_12_16_cbc/","title":"EVP_rc5_32_12_16_cbc","text":""},{"location":"man3/EVP_rc5_32_12_16_cbc/#name","title":"NAME","text":"

EVP_rc5_32_12_16_cbc, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_cfb64, EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_ofb - EVP RC5 cipher

"},{"location":"man3/EVP_rc5_32_12_16_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_rc5_32_12_16_cbc(void);\nconst EVP_CIPHER *EVP_rc5_32_12_16_cfb(void);\nconst EVP_CIPHER *EVP_rc5_32_12_16_cfb64(void);\nconst EVP_CIPHER *EVP_rc5_32_12_16_ecb(void);\nconst EVP_CIPHER *EVP_rc5_32_12_16_ofb(void);\n
"},{"location":"man3/EVP_rc5_32_12_16_cbc/#description","title":"DESCRIPTION","text":"

The RC5 encryption algorithm for EVP.

"},{"location":"man3/EVP_rc5_32_12_16_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-RC5(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_rc5_32_12_16_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_rc5_32_12_16_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_rc5_32_12_16_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_ripemd160/","title":"EVP_ripemd160","text":""},{"location":"man3/EVP_ripemd160/#name","title":"NAME","text":"

EVP_ripemd160 - RIPEMD160 For EVP

"},{"location":"man3/EVP_ripemd160/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_ripemd160(void);\n
"},{"location":"man3/EVP_ripemd160/#description","title":"DESCRIPTION","text":"

RIPEMD-160 is a cryptographic hash function first published in 1996 belonging to the RIPEMD family (RACE Integrity Primitives Evaluation Message Digest). This implementation is only available with the legacy provider.

"},{"location":"man3/EVP_ripemd160/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-RIPEMD160(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_ripemd160/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_ripemd160/#conforming-to","title":"CONFORMING TO","text":"

ISO/IEC 10118-3:2016 Dedicated Hash-Function 1 (RIPEMD-160).

"},{"location":"man3/EVP_ripemd160/#see-also","title":"SEE ALSO","text":"

evp(7), provider(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_ripemd160/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_seed_cbc/","title":"EVP_seed_cbc","text":""},{"location":"man3/EVP_seed_cbc/#name","title":"NAME","text":"

EVP_seed_cbc, EVP_seed_cfb, EVP_seed_cfb128, EVP_seed_ecb, EVP_seed_ofb - EVP SEED cipher

"},{"location":"man3/EVP_seed_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_seed_cbc(void);\nconst EVP_CIPHER *EVP_seed_cfb(void);\nconst EVP_CIPHER *EVP_seed_cfb128(void);\nconst EVP_CIPHER *EVP_seed_ecb(void);\nconst EVP_CIPHER *EVP_seed_ofb(void);\n
"},{"location":"man3/EVP_seed_cbc/#description","title":"DESCRIPTION","text":"

The SEED encryption algorithm for EVP.

All modes below use a key length of 128 bits and acts on blocks of 128-bits.

"},{"location":"man3/EVP_seed_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-SEED(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_seed_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return an EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_seed_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_seed_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_set_default_properties/","title":"EVP_set_default_properties","text":""},{"location":"man3/EVP_set_default_properties/#name","title":"NAME","text":"

EVP_set_default_properties, EVP_default_properties_enable_fips, EVP_default_properties_is_fips_enabled, EVP_get1_default_properties - manage default properties for future algorithm fetches

"},{"location":"man3/EVP_set_default_properties/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_set_default_properties(OSSL_LIB_CTX *libctx, const char *propq);\nchar *EVP_get1_default_properties(OSSL_LIB_CTX *libctx);\nint EVP_default_properties_enable_fips(OSSL_LIB_CTX *libctx, int enable);\nint EVP_default_properties_is_fips_enabled(OSSL_LIB_CTX *libctx);\n
"},{"location":"man3/EVP_set_default_properties/#description","title":"DESCRIPTION","text":"

EVP_set_default_properties() sets the default properties for all future EVP algorithm fetches, implicit as well as explicit. See \"ALGORITHM FETCHING\" in crypto(7) for information about implicit and explicit fetching.

EVP_set_default_properties stores the properties given with the string propq among the EVP data that's been stored in the library context given with libctx (NULL signifies the default library context).

Any previous default property for the specified library context will be dropped.

EVP_get1_default_properties() gets the default properties set for all future EVP algorithm fetches, implicit as well as explicit, for the specific library context.

EVP_default_properties_enable_fips() sets the 'fips=yes' to be a default property if enable is non zero, otherwise it clears 'fips' from the default property query for the given libctx. It merges the fips default property query with any existing query strings that have been set via EVP_set_default_properties().

EVP_default_properties_is_fips_enabled() indicates if 'fips=yes' is a default property for the given libctx.

"},{"location":"man3/EVP_set_default_properties/#notes","title":"NOTES","text":"

EVP_set_default_properties() and EVP_default_properties_enable_fips() are not thread safe. They are intended to be called only during the initialisation phase of a libctx.

EVP_get1_default_properties() is not thread safe. The application must ensure that the context reference is valid and default fetching properties are not being modified by a different thread.

"},{"location":"man3/EVP_set_default_properties/#return-values","title":"RETURN VALUES","text":"

EVP_set_default_properties() and EVP_default_properties_enable_fips() return 1 on success, or 0 on failure. An error is placed on the error stack if a failure occurs.

EVP_default_properties_is_fips_enabled() returns 1 if the 'fips=yes' default property is set for the given libctx, otherwise it returns 0.

EVP_get1_default_properties() returns allocated memory that must be freed by OPENSSL_free(3) on success and NULL on failure.

"},{"location":"man3/EVP_set_default_properties/#see-also","title":"SEE ALSO","text":"

EVP_MD_fetch(3)

"},{"location":"man3/EVP_set_default_properties/#history","title":"HISTORY","text":"

The functions EVP_set_default_properties(), EVP_default_properties_enable_fips(), EVP_default_properties_is_fips_enabled() were added in OpenSSL 3.0.

The function EVP_get1_default_properties() was added in OpenSSL 3.5.

"},{"location":"man3/EVP_set_default_properties/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2021 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.

"},{"location":"man3/EVP_sha1/","title":"EVP_sha1","text":""},{"location":"man3/EVP_sha1/#name","title":"NAME","text":"

EVP_sha1 - SHA-1 For EVP

"},{"location":"man3/EVP_sha1/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_sha1(void);\n
"},{"location":"man3/EVP_sha1/#description","title":"DESCRIPTION","text":"

SHA-1 (Secure Hash Algorithm 1) is a cryptographic hash function standardized in NIST FIPS 180-4. The algorithm was designed by the United States National Security Agency and initially published in 1995.

"},{"location":"man3/EVP_sha1/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-SHA1(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_sha1/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_sha1/#conforming-to","title":"CONFORMING TO","text":"

NIST FIPS 180-4.

"},{"location":"man3/EVP_sha1/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_sha1/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_sha224/","title":"EVP_sha224","text":""},{"location":"man3/EVP_sha224/#name","title":"NAME","text":"

EVP_sha224, EVP_sha256, EVP_sha512_224, EVP_sha512_256, EVP_sha384, EVP_sha512 - SHA-2 For EVP

"},{"location":"man3/EVP_sha224/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_sha224(void);\nconst EVP_MD *EVP_sha256(void);\nconst EVP_MD *EVP_sha512_224(void);\nconst EVP_MD *EVP_sha512_256(void);\nconst EVP_MD *EVP_sha384(void);\nconst EVP_MD *EVP_sha512(void);\n
"},{"location":"man3/EVP_sha224/#description","title":"DESCRIPTION","text":"

SHA-2 (Secure Hash Algorithm 2) is a family of cryptographic hash functions standardized in NIST FIPS 180-4, first published in 2001.

"},{"location":"man3/EVP_sha224/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-SHA2(7)instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_sha224/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_sha224/#conforming-to","title":"CONFORMING TO","text":"

NIST FIPS 180-4.

"},{"location":"man3/EVP_sha224/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_sha224/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_sha3_224/","title":"EVP_sha3_224","text":""},{"location":"man3/EVP_sha3_224/#name","title":"NAME","text":"

EVP_sha3_224, EVP_sha3_256, EVP_sha3_384, EVP_sha3_512, EVP_shake128, EVP_shake256 - SHA-3 For EVP

"},{"location":"man3/EVP_sha3_224/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_sha3_224(void);\nconst EVP_MD *EVP_sha3_256(void);\nconst EVP_MD *EVP_sha3_384(void);\nconst EVP_MD *EVP_sha3_512(void);\n\nconst EVP_MD *EVP_shake128(void);\nconst EVP_MD *EVP_shake256(void);\n
"},{"location":"man3/EVP_sha3_224/#description","title":"DESCRIPTION","text":"

SHA-3 (Secure Hash Algorithm 3) is a family of cryptographic hash functions standardized in NIST FIPS 202, first published in 2015. It is based on the Keccak algorithm.

"},{"location":"man3/EVP_sha3_224/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-SHA3(7) or EVP_MD-SHAKE(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_sha3_224/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_sha3_224/#conforming-to","title":"CONFORMING TO","text":"

NIST FIPS 202.

"},{"location":"man3/EVP_sha3_224/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_sha3_224/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/EVP_sm3/","title":"EVP_sm3","text":""},{"location":"man3/EVP_sm3/#name","title":"NAME","text":"

EVP_sm3 - SM3 for EVP

"},{"location":"man3/EVP_sm3/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_sm3(void);\n
"},{"location":"man3/EVP_sm3/#description","title":"DESCRIPTION","text":"

SM3 is a cryptographic hash function with a 256-bit output, defined in GB/T 32905-2016.

"},{"location":"man3/EVP_sm3/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-SM3(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_sm3/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_sm3/#conforming-to","title":"CONFORMING TO","text":"

GB/T 32905-2016 and GM/T 0004-2012.

"},{"location":"man3/EVP_sm3/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_sm3/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 The OpenSSL Project Authors. All Rights Reserved. Copyright 2017 Ribose Inc. 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.

"},{"location":"man3/EVP_sm4_cbc/","title":"EVP_sm4_cbc","text":""},{"location":"man3/EVP_sm4_cbc/#name","title":"NAME","text":"

EVP_sm4_cbc, EVP_sm4_ecb, EVP_sm4_cfb, EVP_sm4_cfb128, EVP_sm4_ofb, EVP_sm4_ctr - EVP SM4 cipher

"},{"location":"man3/EVP_sm4_cbc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_CIPHER *EVP_sm4_cbc(void);\nconst EVP_CIPHER *EVP_sm4_ecb(void);\nconst EVP_CIPHER *EVP_sm4_cfb(void);\nconst EVP_CIPHER *EVP_sm4_cfb128(void);\nconst EVP_CIPHER *EVP_sm4_ofb(void);\nconst EVP_CIPHER *EVP_sm4_ctr(void);\n
"},{"location":"man3/EVP_sm4_cbc/#description","title":"DESCRIPTION","text":"

The SM4 blockcipher (GB/T 32907-2016) for EVP.

All modes below use a key length of 128 bits and acts on blocks of 128 bits.

"},{"location":"man3/EVP_sm4_cbc/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling these functions multiple times and should consider using EVP_CIPHER_fetch(3) with EVP_CIPHER-SM4(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_sm4_cbc/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_CIPHER structure that contains the implementation of the symmetric cipher. See EVP_CIPHER_meth_new(3) for details of the EVP_CIPHER structure.

"},{"location":"man3/EVP_sm4_cbc/#see-also","title":"SEE ALSO","text":"

evp(7), EVP_EncryptInit(3), EVP_CIPHER_meth_new(3)

"},{"location":"man3/EVP_sm4_cbc/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 The OpenSSL Project Authors. All Rights Reserved. Copyright 2017 Ribose Inc. 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.

"},{"location":"man3/EVP_whirlpool/","title":"EVP_whirlpool","text":""},{"location":"man3/EVP_whirlpool/#name","title":"NAME","text":"

EVP_whirlpool - WHIRLPOOL For EVP

"},{"location":"man3/EVP_whirlpool/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nconst EVP_MD *EVP_whirlpool(void);\n
"},{"location":"man3/EVP_whirlpool/#description","title":"DESCRIPTION","text":"

WHIRLPOOL is a cryptographic hash function standardized in ISO/IEC 10118-3:2004 designed by Vincent Rijmen and Paulo S. L. M. Barreto. This implementation is only available with the legacy provider.

"},{"location":"man3/EVP_whirlpool/#notes","title":"NOTES","text":"

Developers should be aware of the negative performance implications of calling this function multiple times and should consider using EVP_MD_fetch(3) with EVP_MD-WHIRLPOOL(7) instead. See \"Performance\" in crypto(7) for further information.

"},{"location":"man3/EVP_whirlpool/#return-values","title":"RETURN VALUES","text":"

These functions return a EVP_MD structure that contains the implementation of the message digest. See EVP_MD_meth_new(3) for details of the EVP_MD structure.

"},{"location":"man3/EVP_whirlpool/#conforming-to","title":"CONFORMING TO","text":"

ISO/IEC 10118-3:2004.

"},{"location":"man3/EVP_whirlpool/#see-also","title":"SEE ALSO","text":"

evp(7), provider(7), EVP_DigestInit(3)

"},{"location":"man3/EVP_whirlpool/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2023 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.

"},{"location":"man3/GENERAL_NAME/","title":"GENERAL_NAME","text":""},{"location":"man3/GENERAL_NAME/#name","title":"NAME","text":"

GENERAL_NAME, GENERAL_NAME_set1_X509_NAME - GENERAL_NAME method routines

"},{"location":"man3/GENERAL_NAME/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509v3.h>\n\ntypedef struct GENERAL_NAME_st GENERAL_NAME;\n\nint GENERAL_NAME_set1_X509_NAME(GENERAL_NAME **tgt, const X509_NAME *src);\n
"},{"location":"man3/GENERAL_NAME/#description","title":"DESCRIPTION","text":"

GENERAL_NAME_set1_X509_NAME() creates a new GENERAL_NAME of type GEN_DIRNAME and populates it based on provided X509_NAME src which can be NULL. tgt must not be NULL. If successful, *tgt will be set to point to the newly created GENERAL_NAME.

"},{"location":"man3/GENERAL_NAME/#return-values","title":"RETURN VALUES","text":"

GENERAL_NAME_set1_X509_NAME() return 1 on success, 0 on error.

"},{"location":"man3/GENERAL_NAME/#history","title":"HISTORY","text":"

GENERAL_NAME_set1_X509_NAME() was added in OpenSSL 3.4.

"},{"location":"man3/GENERAL_NAME/#copyright","title":"COPYRIGHT","text":"

Copyright 2007-2024 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.

"},{"location":"man3/HMAC/","title":"HMAC","text":""},{"location":"man3/HMAC/#name","title":"NAME","text":"

HMAC, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags, HMAC_CTX_get_md, HMAC_size - HMAC message authentication code

"},{"location":"man3/HMAC/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/hmac.h>\n\nunsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,\n                    const unsigned char *data, size_t data_len,\n                    unsigned char *md, unsigned int *md_len);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

HMAC_CTX *HMAC_CTX_new(void);\nint HMAC_CTX_reset(HMAC_CTX *ctx);\n\nint HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,\n                 const EVP_MD *md, ENGINE *impl);\nint HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len);\nint HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);\n\nvoid HMAC_CTX_free(HMAC_CTX *ctx);\n\nint HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);\nvoid HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);\nconst EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);\n\nsize_t HMAC_size(const HMAC_CTX *e);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,\n              const EVP_MD *md);\n
"},{"location":"man3/HMAC/#description","title":"DESCRIPTION","text":"

HMAC is a MAC (message authentication code), i.e. a keyed hash function used for message authentication, which is based on a hash function.

HMAC() computes the message authentication code of the data_len bytes at data using the hash function evp_md and the key key which is key_len bytes long. The key may also be NULL with key_len being 0.

It places the result in md (which must have space for the output of the hash function, which is no more than EVP_MAX_MD_SIZE bytes). If md is NULL, the digest is placed in a static array. The size of the output is placed in md_len, unless it is NULL. Note: passing a NULL value for md to use the static array is not thread safe.

evp_md is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does not support variable output length digests such as EVP_shake128() and EVP_shake256().

HMAC() uses the default OSSL_LIB_CTX. Use EVP_Q_mac(3) instead if a library context is required.

All of the functions described below are deprecated. Applications should instead use EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3), EVP_MAC_update(3) and EVP_MAC_final(3) or the 'quick' single-shot MAC function EVP_Q_mac(3).

HMAC_CTX_new() creates a new HMAC_CTX in heap memory.

HMAC_CTX_reset() clears an existing HMAC_CTX and associated resources, making it suitable for new computations as if it was newly created with HMAC_CTX_new().

HMAC_CTX_free() erases the key and other data from the HMAC_CTX, releases any associated resources and finally frees the HMAC_CTX itself. If the argument is NULL, nothing is done.

The following functions may be used if the message is not completely stored in memory:

HMAC_Init_ex() initializes or reuses a HMAC_CTX structure to use the hash function evp_md and key key. If both are NULL, or if key is NULL and evp_md is the same as the previous call, then the existing key is reused. ctx must have been created with HMAC_CTX_new() before the first use of an HMAC_CTX in this function.

If HMAC_Init_ex() is called with key NULL and evp_md is not the same as the previous digest used by ctx then an error is returned because reuse of an existing key with a different digest is not supported.

HMAC_Init() initializes a HMAC_CTX structure to use the hash function evp_md and the key key which is key_len bytes long.

HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (len bytes at data).

HMAC_Final() places the message authentication code in md, which must have space for the hash function output.

HMAC_CTX_copy() copies all of the internal state from sctx into dctx.

HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs. These flags have the same meaning as for EVP_MD_CTX_set_flags(3).

HMAC_CTX_get_md() returns the EVP_MD that has previously been set for the supplied HMAC_CTX.

HMAC_size() returns the length in bytes of the underlying hash function output.

"},{"location":"man3/HMAC/#return-values","title":"RETURN VALUES","text":"

HMAC() returns a pointer to the message authentication code or NULL if an error occurred.

HMAC_CTX_new() returns a pointer to a new HMAC_CTX on success or NULL if an error occurred.

HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and HMAC_CTX_copy() return 1 for success or 0 if an error occurred.

HMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or NULL if no EVP_MD has been set.

HMAC_size() returns the length in bytes of the underlying hash function output or zero on error.

"},{"location":"man3/HMAC/#conforming-to","title":"CONFORMING TO","text":"

RFC 2104

"},{"location":"man3/HMAC/#see-also","title":"SEE ALSO","text":"

SHA1(3), EVP_Q_mac(3), evp(7)

"},{"location":"man3/HMAC/#history","title":"HISTORY","text":"

All functions except for HMAC() were deprecated in OpenSSL 3.0.

HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL 1.1.0.

HMAC_CTX_cleanup() existed in OpenSSL before version 1.1.0.

HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL 1.1.0.

HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in OpenSSL before version 1.0.0.

"},{"location":"man3/HMAC/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/MD5/","title":"MD5","text":""},{"location":"man3/MD5/#name","title":"NAME","text":"

MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions

"},{"location":"man3/MD5/#synopsis","title":"SYNOPSIS","text":"

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/md2.h>\n\nunsigned char *MD2(const unsigned char *d, unsigned long n, unsigned char *md);\n\nint MD2_Init(MD2_CTX *c);\nint MD2_Update(MD2_CTX *c, const unsigned char *data, unsigned long len);\nint MD2_Final(unsigned char *md, MD2_CTX *c);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/md4.h>\n\nunsigned char *MD4(const unsigned char *d, unsigned long n, unsigned char *md);\n\nint MD4_Init(MD4_CTX *c);\nint MD4_Update(MD4_CTX *c, const void *data, unsigned long len);\nint MD4_Final(unsigned char *md, MD4_CTX *c);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/md5.h>\n\nunsigned char *MD5(const unsigned char *d, unsigned long n, unsigned char *md);\n\nint MD5_Init(MD5_CTX *c);\nint MD5_Update(MD5_CTX *c, const void *data, unsigned long len);\nint MD5_Final(unsigned char *md, MD5_CTX *c);\n
"},{"location":"man3/MD5/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_DigestInit_ex(3), EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3).

MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.

MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest of the n bytes at d and place it in md (which must have space for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 bytes of output). If md is NULL, the digest is placed in a static array.

The following functions may be used if the message is not completely stored in memory:

MD2_Init() initializes a MD2_CTX structure.

MD2_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at data).

MD2_Final() places the message digest in md, which must have space for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the MD2_CTX.

MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() are analogous using an MD4_CTX and MD5_CTX structure. The parameter MUST NOT be NULL.

Applications should use the higher level functions EVP_DigestInit(3) etc. instead of calling the hash functions directly.

"},{"location":"man3/MD5/#note","title":"NOTE","text":"

MD2, MD4, and MD5 are recommended only for compatibility with existing applications. In new applications, hashes from the SHA-2 or SHA-3 family should be preferred.

"},{"location":"man3/MD5/#return-values","title":"RETURN VALUES","text":"

MD2(), MD4(), and MD5() return pointers to the hash value.

MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for success, 0 otherwise.

"},{"location":"man3/MD5/#conforming-to","title":"CONFORMING TO","text":"

RFC 1319, RFC 1320, RFC 1321

"},{"location":"man3/MD5/#see-also","title":"SEE ALSO","text":"

EVP_DigestInit(3), EVP_MD-SHA2(7), EVP_MD-SHA3(7)

"},{"location":"man3/MD5/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/MD5/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/MDC2_Init/","title":"MDC2_Init","text":""},{"location":"man3/MDC2_Init/#name","title":"NAME","text":"

MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function

"},{"location":"man3/MDC2_Init/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/mdc2.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

unsigned char *MDC2(const unsigned char *d, unsigned long n,\n                    unsigned char *md);\n\nint MDC2_Init(MDC2_CTX *c);\nint MDC2_Update(MDC2_CTX *c, const unsigned char *data,\n                unsigned long len);\nint MDC2_Final(unsigned char *md, MDC2_CTX *c);\n
"},{"location":"man3/MDC2_Init/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_DigestInit_ex(3), EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3).

MDC2 is a method to construct hash functions with 128 bit output from block ciphers. These functions are an implementation of MDC2 with DES.

MDC2() computes the MDC2 message digest of the n bytes at d and places it in md (which must have space for MDC2_DIGEST_LENGTH == 16 bytes of output). If md is NULL, the digest is placed in a static array.

The following functions may be used if the message is not completely stored in memory:

MDC2_Init() initializes a MDC2_CTX structure.

MDC2_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at data).

MDC2_Final() places the message digest in md, which must have space for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the MDC2_CTX.

Applications should use the higher level functions EVP_DigestInit(3) etc. instead of calling the hash functions directly.

"},{"location":"man3/MDC2_Init/#return-values","title":"RETURN VALUES","text":"

MDC2() returns a pointer to the hash value.

MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise.

"},{"location":"man3/MDC2_Init/#conforming-to","title":"CONFORMING TO","text":"

ISO/IEC 10118-2:2000 Hash-Function 2, with DES as the underlying block cipher.

"},{"location":"man3/MDC2_Init/#see-also","title":"SEE ALSO","text":"

EVP_DigestInit(3)

"},{"location":"man3/MDC2_Init/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/MDC2_Init/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/NCONF_new_ex/","title":"NCONF_new_ex","text":""},{"location":"man3/NCONF_new_ex/#name","title":"NAME","text":"

NCONF_new_ex, NCONF_new, NCONF_free, NCONF_default, NCONF_load, NCONF_get0_libctx, NCONF_get_section, NCONF_get_section_names - functionality to Load and parse configuration files manually

"},{"location":"man3/NCONF_new_ex/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\ntypedef struct {\n    char *section;\n    char *name;\n    char *value;\n} CONF_VALUE;\n\nCONF *NCONF_new_ex(OSSL_LIB_CTX *libctx, CONF_METHOD *meth);\nCONF *NCONF_new(CONF_METHOD *meth);\nvoid NCONF_free(CONF *conf);\nCONF_METHOD *NCONF_default(void);\nint NCONF_load(CONF *conf, const char *file, long *eline);\nOSSL_LIB_CTX *NCONF_get0_libctx(const CONF *conf);\n\nSTACK_OF(CONF_VALUE) *NCONF_get_section(const CONF *conf, const char *name);\nSTACK_OF(OPENSSL_CSTRING) *NCONF_get_section_names(const CONF *conf);\n
"},{"location":"man3/NCONF_new_ex/#description","title":"DESCRIPTION","text":"

NCONF_new_ex() creates a new CONF object in heap memory and assigns to it a context libctx that can be used during loading. If the method table meth is set to NULL then the default value of NCONF_default() is used.

NCONF_new() is similar to NCONF_new_ex() but sets the libctx to NULL.

NCONF_free() frees the data associated with conf and then frees the conf object. If the argument is NULL, nothing is done.

NCONF_load() parses the file named filename and adds the values found to conf. If an error occurs file and eline list the file and line that the load failed on if they are not NULL.

NCONF_default() gets the default method table for processing a configuration file.

NCONF_get0_libctx() gets the library context associated with the conf parameter.

NCONF_get_section_names() gets the names of the sections associated with the conf as STACK_OF(OPENSSL_CSTRING) strings. The individual strings are associated with the conf and will be invalid after conf is freed. The returned stack must be freed with sk_OPENSSL_CSTRING_free().

NCONF_get_section() gets the config values associated with the conf from the config section name as STACK_OF(CONF_VALUE) structures. The returned stack is associated with the conf and will be invalid after conf is freed. It must not be freed by the caller.

"},{"location":"man3/NCONF_new_ex/#return-values","title":"RETURN VALUES","text":"

NCONF_load() returns 1 on success or 0 on error.

NCONF_new_ex() and NCONF_new() return a newly created CONF object or NULL if an error occurs.

"},{"location":"man3/NCONF_new_ex/#see-also","title":"SEE ALSO","text":"

CONF_modules_load_file(3),

"},{"location":"man3/NCONF_new_ex/#history","title":"HISTORY","text":"

NCONF_new_ex(), NCONF_get0_libctx(), and NCONF_get_section_names() were added in OpenSSL 3.0.

"},{"location":"man3/NCONF_new_ex/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2024 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.

"},{"location":"man3/OBJ_nid2obj/","title":"OBJ_nid2obj","text":""},{"location":"man3/OBJ_nid2obj/#name","title":"NAME","text":"

i2t_ASN1_OBJECT, OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup, OBJ_add_sigid - ASN1 object utility functions

"},{"location":"man3/OBJ_nid2obj/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/objects.h>\n\nASN1_OBJECT *OBJ_nid2obj(int n);\nconst char *OBJ_nid2ln(int n);\nconst char *OBJ_nid2sn(int n);\n\nint OBJ_obj2nid(const ASN1_OBJECT *o);\nint OBJ_ln2nid(const char *ln);\nint OBJ_sn2nid(const char *sn);\n\nint OBJ_txt2nid(const char *s);\n\nASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name);\nint OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);\n\nint i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);\n\nint OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);\nASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);\n\nint OBJ_create(const char *oid, const char *sn, const char *ln);\n\nsize_t OBJ_length(const ASN1_OBJECT *obj);\nconst unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);\n\nint OBJ_add_sigid(int signid, int dig_id, int pkey_id);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void OBJ_cleanup(void);\n
"},{"location":"man3/OBJ_nid2obj/#description","title":"DESCRIPTION","text":"

The ASN1 object utility functions process ASN1_OBJECT structures which are a representation of the ASN1 OBJECT IDENTIFIER (OID) type. For convenience, OIDs are usually represented in source code as numeric identifiers, or NIDs. OpenSSL has an internal table of OIDs that are generated when the library is built, and their corresponding NIDs are available as defined constants. For the functions below, application code should treat all returned values -- OIDs, NIDs, or names -- as constants.

OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID n to an ASN1_OBJECT structure, its long name and its short name respectively, or NULL if an error occurred.

OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID for the object o, the long name ln or the short name sn respectively or NID_undef if an error occurred.

OBJ_txt2nid() returns NID corresponding to text string s. s can be a long name, a short name or the numerical representation of an object.

OBJ_txt2obj() converts the text string s into an ASN1_OBJECT structure. If no_name is 0 then long names and short names will be interpreted as well as numerical forms. If no_name is 1 only the numerical form is acceptable.

OBJ_obj2txt() converts the ASN1_OBJECT a into a textual representation. Unless buf is NULL, the representation is written as a NUL-terminated string to buf, where at most buf_len bytes are written, truncating the result if necessary. In any case it returns the total string length, excluding the NUL character, required for non-truncated representation, or -1 on error. If no_name is 0 then if the object has a long or short name then that will be used, otherwise the numerical form will be used. If no_name is 1 then the numerical form will always be used.

i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the no_name set to zero.

OBJ_cmp() compares a to b. If the two are identical 0 is returned.

OBJ_dup() returns a copy of o.

OBJ_create() adds a new object to the internal table. oid is the numerical form of the object, sn the short name and ln the long name. A new NID is returned for the created object in case of success and NID_undef in case of failure. Any of oid, sn and ln may be NULL, but not all at once.

OBJ_length() returns the size of the content octets of obj.

OBJ_get0_data() returns a pointer to the content octets of obj. The returned pointer is an internal pointer which must not be freed.

OBJ_add_sigid() creates a new composite \"Signature Algorithm\" that associates a given NID with two other NIDs - one representing the underlying signature algorithm and the other representing a digest algorithm to be used in conjunction with it. signid represents the NID for the composite \"Signature Algorithm\", dig_id is the NID for the digest algorithm and pkey_id is the NID for the underlying signature algorithm. As there are signature algorithms that do not require a digest, NID_undef is a valid dig_id.

OBJ_cleanup() releases any resources allocated by creating new objects.

"},{"location":"man3/OBJ_nid2obj/#notes","title":"NOTES","text":"

Objects in OpenSSL can have a short name, a long name and a numerical identifier (NID) associated with them. A standard set of objects is represented in an internal table. The appropriate values are defined in the header file objects.h.

For example the OID for commonName has the following definitions:

#define SN_commonName                   \"CN\"\n#define LN_commonName                   \"commonName\"\n#define NID_commonName                  13\n

New objects can be added by calling OBJ_create().

Table objects have certain advantages over other objects: for example their NIDs can be used in a C language switch statement. They are also static constant structures which are shared: that is there is only a single constant structure for each table object.

Objects which are not in the table have the NID value NID_undef.

Objects do not need to be in the internal tables to be processed, the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical form of an OID.

Some objects are used to represent algorithms which do not have a corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently exists for a particular algorithm). As a result they cannot be encoded or decoded as part of ASN.1 structures. Applications can determine if there is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.

These functions cannot return const because an ASN1_OBJECT can represent both an internal, constant, OID and a dynamically-created one. The latter cannot be constant because it needs to be freed after use.

These functions were not thread safe in OpenSSL 3.0 and before.

"},{"location":"man3/OBJ_nid2obj/#return-values","title":"RETURN VALUES","text":"

OBJ_nid2obj() returns an ASN1_OBJECT structure or NULL is an error occurred.

OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or NULL on error.

OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or NID_undef on error.

OBJ_add_sigid() returns 1 on success or 0 on error.

i2t_ASN1_OBJECT() an OBJ_obj2txt() return -1 on error. On success, they return the length of the string written to buf if buf is not NULL and buf_len is big enough, otherwise the total string length. Note that this does not count the trailing NUL character.

"},{"location":"man3/OBJ_nid2obj/#examples","title":"EXAMPLES","text":"

Create an object for commonName:

ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName);\n

Check if an object is commonName

if (OBJ_obj2nid(obj) == NID_commonName)\n    /* Do something */\n

Create a new NID and initialize an object from it:

int new_nid = OBJ_create(\"1.2.3.4\", \"NewOID\", \"New Object Identifier\");\nASN1_OBJECT *obj = OBJ_nid2obj(new_nid);\n

Create a new object directly:

obj = OBJ_txt2obj(\"1.2.3.4\", 1);\n
"},{"location":"man3/OBJ_nid2obj/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/OBJ_nid2obj/#history","title":"HISTORY","text":"

OBJ_cleanup() was deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(3) and should not be used.

"},{"location":"man3/OBJ_nid2obj/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2021 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.

"},{"location":"man3/OCSP_REQUEST_new/","title":"OCSP_REQUEST_new","text":""},{"location":"man3/OCSP_REQUEST_new/#name","title":"NAME","text":"

OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign, OCSP_request_add1_cert, OCSP_request_onereq_count, OCSP_request_onereq_get0 - OCSP request functions

"},{"location":"man3/OCSP_REQUEST_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nOCSP_REQUEST *OCSP_REQUEST_new(void);\nvoid OCSP_REQUEST_free(OCSP_REQUEST *req);\n\nOCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);\n\nint OCSP_request_sign(OCSP_REQUEST *req,\n                      X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,\n                      STACK_OF(X509) *certs, unsigned long flags);\n\nint OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);\n\nint OCSP_request_onereq_count(OCSP_REQUEST *req);\nOCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);\n
"},{"location":"man3/OCSP_REQUEST_new/#description","title":"DESCRIPTION","text":"

OCSP_REQUEST_new() allocates and returns an empty OCSP_REQUEST structure.

OCSP_REQUEST_free() frees up the request structure req. If the argument is NULL, nothing is done.

OCSP_request_add0_id() adds certificate ID cid to req. It returns the OCSP_ONEREQ structure added so an application can add additional extensions to the request. The id parameter MUST NOT be freed up after the operation.

OCSP_request_sign() signs OCSP request req using certificate signer, private key key, digest dgst and additional certificates certs. If the flags option OCSP_NOCERTS is set then no certificates will be included in the request.

OCSP_request_add1_cert() adds certificate cert to request req. The application is responsible for freeing up cert after use.

OCSP_request_onereq_count() returns the total number of OCSP_ONEREQ structures in req.

OCSP_request_onereq_get0() returns an internal pointer to the OCSP_ONEREQ contained in req of index i. The index value i runs from 0 to OCSP_request_onereq_count(req) - 1.

"},{"location":"man3/OCSP_REQUEST_new/#return-values","title":"RETURN VALUES","text":"

OCSP_REQUEST_new() returns an empty OCSP_REQUEST structure or NULL if an error occurred.

OCSP_request_add0_id() returns the OCSP_ONEREQ structure containing cid or NULL if an error occurred.

OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0 for failure.

OCSP_request_onereq_count() returns the total number of OCSP_ONEREQ structures in req and -1 on error.

OCSP_request_onereq_get0() returns a pointer to an OCSP_ONEREQ structure or NULL if the index value is out or range.

"},{"location":"man3/OCSP_REQUEST_new/#notes","title":"NOTES","text":"

An OCSP request structure contains one or more OCSP_ONEREQ structures corresponding to each certificate.

OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by OCSP responders.

"},{"location":"man3/OCSP_REQUEST_new/#examples","title":"EXAMPLES","text":"

Create an OCSP_REQUEST structure for certificate cert with issuer issuer:

OCSP_REQUEST *req;\nOCSP_ID *cid;\n\nreq = OCSP_REQUEST_new();\nif (req == NULL)\n   /* error */\ncid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);\nif (cid == NULL)\n   /* error */\n\nif (OCSP_REQUEST_add0_id(req, cid) == NULL)\n   /* error */\n\n/* Do something with req, e.g. query responder */\n\nOCSP_REQUEST_free(req);\n
"},{"location":"man3/OCSP_REQUEST_new/#see-also","title":"SEE ALSO","text":"

crypto(7), OCSP_cert_to_id(3), OCSP_request_add1_nonce(3), OCSP_resp_find_status(3), OCSP_response_status(3), OCSP_sendreq_new(3)

"},{"location":"man3/OCSP_REQUEST_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/OCSP_cert_to_id/","title":"OCSP_cert_to_id","text":""},{"location":"man3/OCSP_cert_to_id/#name","title":"NAME","text":"

OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp, OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions

"},{"location":"man3/OCSP_cert_to_id/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nOCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst,\n                             X509 *subject, X509 *issuer);\n\nOCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst,\n                              X509_NAME *issuerName,\n                              ASN1_BIT_STRING *issuerKey,\n                              ASN1_INTEGER *serialNumber);\n\nvoid OCSP_CERTID_free(OCSP_CERTID *id);\n\nint OCSP_id_issuer_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);\nint OCSP_id_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);\n\nint OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,\n                      ASN1_OCTET_STRING **pikeyHash,\n                      ASN1_INTEGER **pserial, OCSP_CERTID *cid);\n
"},{"location":"man3/OCSP_cert_to_id/#description","title":"DESCRIPTION","text":"

OCSP_cert_to_id() creates and returns a new OCSP_CERTID structure using message digest dgst for certificate subject with issuer issuer. If dgst is NULL then SHA1 is used.

OCSP_cert_id_new() creates and returns a new OCSP_CERTID using dgst and issuer name issuerName, issuer key hash issuerKey and serial number serialNumber.

OCSP_CERTID_free() frees up id. If the argument is NULL, nothing is done.

OCSP_id_cmp() compares OCSP_CERTID a and b.

OCSP_id_issuer_cmp() compares only the issuer name of OCSP_CERTID a and b.

OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and serial number contained in cid. If any of the values are not required the corresponding parameter can be set to NULL.

"},{"location":"man3/OCSP_cert_to_id/#return-values","title":"RETURN VALUES","text":"

OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid OCSP_CERTID structure or NULL if an error occurred.

OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and nonzero otherwise.

OCSP_CERTID_free() does not return a value.

OCSP_id_get0_info() returns 1 for success and 0 for failure.

"},{"location":"man3/OCSP_cert_to_id/#notes","title":"NOTES","text":"

OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new(): the other functions are used by responder applications.

The values returned by OCSP_id_get0_info() are internal pointers and MUST NOT be freed up by an application: they will be freed when the corresponding OCSP_CERTID structure is freed.

"},{"location":"man3/OCSP_cert_to_id/#see-also","title":"SEE ALSO","text":"

crypto(7), OCSP_request_add1_nonce(3), OCSP_REQUEST_new(3), OCSP_resp_find_status(3), OCSP_response_status(3), OCSP_sendreq_new(3)

"},{"location":"man3/OCSP_cert_to_id/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/OCSP_request_add1_nonce/","title":"OCSP_request_add1_nonce","text":""},{"location":"man3/OCSP_request_add1_nonce/#name","title":"NAME","text":"

OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions

"},{"location":"man3/OCSP_request_add1_nonce/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nint OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len);\nint OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len);\nint OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req);\nint OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp);\n
"},{"location":"man3/OCSP_request_add1_nonce/#description","title":"DESCRIPTION","text":"

OCSP_request_add1_nonce() adds a nonce of value val and length len to OCSP request req. If val is NULL a random nonce is used. If len is zero or negative a default length will be used (currently 16 bytes).

OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except it adds a nonce to OCSP basic response resp.

OCSP_check_nonce() compares the nonce value in req and resp.

OCSP_copy_nonce() copies any nonce value present in req to resp.

"},{"location":"man3/OCSP_request_add1_nonce/#return-values","title":"RETURN VALUES","text":"

OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success and 0 for failure.

OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce was present in req and 0 if an error occurred.

OCSP_check_nonce() returns the result of the nonce comparison between req and resp. The return value indicates the result of the comparison. If nonces are present and equal 1 is returned. If the nonces are absent 2 is returned. If a nonce is present in the response only 3 is returned. If nonces are present and unequal 0 is returned. If the nonce is present in the request only then -1 is returned.

"},{"location":"man3/OCSP_request_add1_nonce/#notes","title":"NOTES","text":"

For most purposes the nonce value in a request is set to a random value so the val parameter in OCSP_request_add1_nonce() is usually NULL.

An OCSP nonce is typically added to an OCSP request to thwart replay attacks by checking the same nonce value appears in the response.

Some responders may include a nonce in all responses even if one is not supplied.

Some responders cache OCSP responses and do not sign each response for performance reasons. As a result they do not support nonces.

The return values of OCSP_check_nonce() can be checked to cover each case. A positive return value effectively indicates success: nonces are both present and match, both absent or present in the response only. A nonzero return additionally covers the case where the nonce is present in the request only: this will happen if the responder doesn't support nonces. A zero return value indicates present and mismatched nonces: this should be treated as an error condition.

"},{"location":"man3/OCSP_request_add1_nonce/#see-also","title":"SEE ALSO","text":"

crypto(7), OCSP_cert_to_id(3), OCSP_REQUEST_new(3), OCSP_resp_find_status(3), OCSP_response_status(3), OCSP_sendreq_new(3)

"},{"location":"man3/OCSP_request_add1_nonce/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/OCSP_resp_find_status/","title":"OCSP_resp_find_status","text":""},{"location":"man3/OCSP_resp_find_status/#name","title":"NAME","text":"

OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, OCSP_resp_get0_produced_at, OCSP_resp_get0_signature, OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata, OCSP_resp_get0_certs, OCSP_resp_get0_signer, OCSP_resp_get0_id, OCSP_resp_get1_id, OCSP_check_validity, OCSP_basic_verify - OCSP response utility functions

"},{"location":"man3/OCSP_resp_find_status/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nint OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,\n                          int *reason,\n                          ASN1_GENERALIZEDTIME **revtime,\n                          ASN1_GENERALIZEDTIME **thisupd,\n                          ASN1_GENERALIZEDTIME **nextupd);\n\nint OCSP_resp_count(OCSP_BASICRESP *bs);\nOCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);\nint OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);\nint OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,\n                            ASN1_GENERALIZEDTIME **revtime,\n                            ASN1_GENERALIZEDTIME **thisupd,\n                            ASN1_GENERALIZEDTIME **nextupd);\n\nconst ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(\n                            const OCSP_BASICRESP* single);\n\nconst ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs);\nconst X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs);\nconst OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs);\nconst STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);\n\nint OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,\n                          STACK_OF(X509) *extra_certs);\n\nint OCSP_resp_get0_id(const OCSP_BASICRESP *bs,\n                      const ASN1_OCTET_STRING **pid,\n                      const X509_NAME **pname);\nint OCSP_resp_get1_id(const OCSP_BASICRESP *bs,\n                      ASN1_OCTET_STRING **pid,\n                      X509_NAME **pname);\n\nint OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,\n                        ASN1_GENERALIZEDTIME *nextupd,\n                        long sec, long maxsec);\n\nint OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs,\n                     X509_STORE *st, unsigned long flags);\n
"},{"location":"man3/OCSP_resp_find_status/#description","title":"DESCRIPTION","text":"

OCSP_resp_find_status() searches bs for an OCSP response for id. If it is successful the fields of the response are returned in *status, *reason, *revtime, *thisupd and *nextupd. The *status value will be one of V_OCSP_CERTSTATUS_GOOD, V_OCSP_CERTSTATUS_REVOKED or V_OCSP_CERTSTATUS_UNKNOWN. The *reason and *revtime fields are only set if the status is V_OCSP_CERTSTATUS_REVOKED. If set the *reason field will be set to the revocation reason which will be one of OCSP_REVOKED_STATUS_NOSTATUS, OCSP_REVOKED_STATUS_UNSPECIFIED, OCSP_REVOKED_STATUS_KEYCOMPROMISE, OCSP_REVOKED_STATUS_CACOMPROMISE, OCSP_REVOKED_STATUS_AFFILIATIONCHANGED, OCSP_REVOKED_STATUS_SUPERSEDED, OCSP_REVOKED_STATUS_CESSATIONOFOPERATION, OCSP_REVOKED_STATUS_CERTIFICATEHOLD or OCSP_REVOKED_STATUS_REMOVEFROMCRL.

OCSP_resp_count() returns the number of OCSP_SINGLERESP structures in bs.

OCSP_resp_get0() returns the OCSP_SINGLERESP structure in bs corresponding to index idx, where idx runs from 0 to OCSP_resp_count(bs) - 1.

OCSP_resp_find() searches bs for id and returns the index of the first matching entry after last or starting from the beginning if last is -1.

OCSP_single_get0_status() extracts the fields of single in *reason, *revtime, *thisupd and *nextupd.

OCSP_resp_get0_produced_at() extracts the producedAt field from the single response bs.

OCSP_resp_get0_signature() returns the signature from bs.

OCSP_resp_get0_tbs_sigalg() returns the signatureAlgorithm from bs.

OCSP_resp_get0_respdata() returns the tbsResponseData from bs.

OCSP_resp_get0_certs() returns any certificates included in bs.

OCSP_resp_get0_signer() attempts to retrieve the certificate that directly signed bs. The OCSP protocol does not require that this certificate is included in the certs field of the response, so additional certificates can be supplied via the extra_certs if the certificates that may have signed the response are known via some out-of-band mechanism.

OCSP_resp_get0_id() gets the responder id of bs. If the responder ID is a name then <*pname> is set to the name and *pid is set to NULL. If the responder ID is by key ID then *pid is set to the key ID and *pname is set to NULL.

OCSP_resp_get1_id() is the same as OCSP_resp_get0_id() but leaves ownership of *pid and *pname with the caller, who is responsible for freeing them unless the function returns 0.

OCSP_check_validity() checks the validity of its thisupd and nextupd arguments, which will be typically obtained from OCSP_resp_find_status() or OCSP_single_get0_status(). If sec is nonzero it indicates how many seconds leeway should be allowed in the check. If maxsec is positive it indicates the maximum age of thisupd in seconds.

OCSP_basic_verify() checks that the basic response message bs is correctly signed and that the signer certificate can be validated. It takes st as the trusted store and certs as a set of untrusted intermediate certificates. The function first tries to find the signer certificate of the response in certs. It then searches the certificates the responder may have included in bs unless flags contains OCSP_NOINTERN. It fails if the signer certificate cannot be found. Next, unless flags contains OCSP_NOSIGS, the function checks the signature of bs and fails on error. Then the function already returns success if flags contains OCSP_NOVERIFY or if the signer certificate was found in certs and flags contains OCSP_TRUSTOTHER. Otherwise the function continues by validating the signer certificate. If flags contains OCSP_PARTIAL_CHAIN it takes intermediate CA certificates in st as trust anchors. For more details, see the description of X509_V_FLAG_PARTIAL_CHAIN in \"VERIFICATION FLAGS\" in X509_VERIFY_PARAM_set_flags(3). If flags contains OCSP_NOCHAIN it ignores all certificates in certs and in bs, else it takes them as untrusted intermediate CA certificates and uses them for constructing the validation path for the signer certificate. Certificate revocation status checks using CRLs is disabled during path validation if the signer certificate contains the id-pkix-ocsp-no-check extension. After successful path validation the function returns success if the OCSP_NOCHECKS flag is set. Otherwise it verifies that the signer certificate meets the OCSP issuer criteria including potential delegation. If this does not succeed and the OCSP_NOEXPLICIT flag is not set the function checks for explicit trust for OCSP signing in the root CA certificate.

"},{"location":"man3/OCSP_resp_find_status/#return-values","title":"RETURN VALUES","text":"

OCSP_resp_find_status() returns 1 if id is found in bs and 0 otherwise.

OCSP_resp_count() returns the total number of OCSP_SINGLERESP fields in bs or -1 on error.

OCSP_resp_get0() returns a pointer to an OCSP_SINGLERESP structure or NULL on error, such as idx being out of range.

OCSP_resp_find() returns the index of id in bs (which may be 0) or -1 on error, such as when id was not found.

OCSP_single_get0_status() returns the status of single or -1 if an error occurred.

OCSP_resp_get0_produced_at() returns the producedAt field from bs.

OCSP_resp_get0_signature() returns the signature from bs.

OCSP_resp_get0_tbs_sigalg() returns the signatureAlgorithm field from bs.

OCSP_resp_get0_respdata() returns the tbsResponseData field from bs.

OCSP_resp_get0_certs() returns any certificates included in bs.

OCSP_resp_get0_signer() returns 1 if the signing certificate was located, or 0 if not found or on error.

OCSP_resp_get0_id() and OCSP_resp_get1_id() return 1 on success, 0 on failure.

OCSP_check_validity() returns 1 if thisupd and nextupd are valid time values and the current time + sec is not before thisupd and, if maxsec >= 0, the current time - maxsec is not past nextupd. Otherwise it returns 0 to indicate an error.

OCSP_basic_verify() returns 1 on success, 0 on verification not successful, or -1 on a fatal error such as malloc failure.

"},{"location":"man3/OCSP_resp_find_status/#notes","title":"NOTES","text":"

Applications will typically call OCSP_resp_find_status() using the certificate ID of interest and then check its validity using OCSP_check_validity(). They can then take appropriate action based on the status of the certificate.

An OCSP response for a certificate contains thisUpdate and nextUpdate fields. Normally the current time should be between these two values. To account for clock skew the maxsec field can be set to nonzero in OCSP_check_validity(). Some responders do not set the nextUpdate field, this would otherwise mean an ancient response would be considered valid: the maxsec parameter to OCSP_check_validity() can be used to limit the permitted age of responses.

The values written to *revtime, *thisupd and *nextupd by OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers which MUST NOT be freed up by the calling application. Any or all of these parameters can be set to NULL if their value is not required.

"},{"location":"man3/OCSP_resp_find_status/#see-also","title":"SEE ALSO","text":"

crypto(7), OCSP_cert_to_id(3), OCSP_request_add1_nonce(3), OCSP_REQUEST_new(3), OCSP_response_status(3), OCSP_sendreq_new(3), X509_VERIFY_PARAM_set_flags(3)

"},{"location":"man3/OCSP_resp_find_status/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2022 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.

"},{"location":"man3/OCSP_response_status/","title":"OCSP_response_status","text":""},{"location":"man3/OCSP_response_status/#name","title":"NAME","text":"

OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create, OCSP_RESPONSE_free, OCSP_RESPID_set_by_name, OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex, OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx - OCSP response functions

"},{"location":"man3/OCSP_response_status/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nint OCSP_response_status(OCSP_RESPONSE *resp);\nOCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);\nOCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);\nvoid OCSP_RESPONSE_free(OCSP_RESPONSE *resp);\n\nint OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);\nint OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert,\n                              OSSL_LIB_CTX *libctx, const char *propq);\nint OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);\nint OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OSSL_LIB_CTX *libctx,\n                         const char *propq);\nint OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);\n\nint OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key,\n                    const EVP_MD *dgst, STACK_OF(X509) *certs,\n                    unsigned long flags);\nint OCSP_basic_sign_ctx(OCSP_BASICRESP *brsp, X509 *signer, EVP_MD_CTX *ctx,\n                        STACK_OF(X509) *certs, unsigned long flags);\n
"},{"location":"man3/OCSP_response_status/#description","title":"DESCRIPTION","text":"

OCSP_response_status() returns the OCSP response status of resp. It returns one of the values: OCSP_RESPONSE_STATUS_SUCCESSFUL, OCSP_RESPONSE_STATUS_MALFORMEDREQUEST, OCSP_RESPONSE_STATUS_INTERNALERROR, OCSP_RESPONSE_STATUS_TRYLATER OCSP_RESPONSE_STATUS_SIGREQUIRED, or OCSP_RESPONSE_STATUS_UNAUTHORIZED.

OCSP_response_get1_basic() decodes and returns the OCSP_BASICRESP structure contained in resp.

OCSP_response_create() creates and returns an OCSP_RESPONSE structure for status and optionally including basic response bs.

OCSP_RESPONSE_free() frees up OCSP response resp. If the argument is NULL, nothing is done.

OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the subject name in the supplied X509 certificate cert for the OCSP responder.

OCSP_RESPID_set_by_key_ex() sets the key of the OCSP_RESPID to be the same as the key in the supplied X509 certificate cert for the OCSP responder. The key is stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using the library ctx libctx and the property query string propq (see \"ALGORITHM FETCHING\" in crypto(7) for further information).

OCSP_RESPID_set_by_key() does the same as OCSP_RESPID_set_by_key_ex() except that the default library context is used with an empty property query string.

Note that an OCSP_RESPID can only have one of the name, or the key set. Calling OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing setting.

OCSP_RESPID_match_ex() tests whether the OCSP_RESPID given in respid matches with the X509 certificate cert based on the SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using the library ctx libctx and the property query string propq (see \"ALGORITHM FETCHING\" in crypto(7) for further information).

OCSP_RESPID_match() does the same as OCSP_RESPID_match_ex() except that the default library context is used with an empty property query string.

OCSP_basic_sign() signs OCSP response brsp using certificate signer, private key key, digest dgst and additional certificates certs. If the flags option OCSP_NOCERTS is set then no certificates will be included in the response. If the flags option OCSP_RESPID_KEY is set then the responder is identified by key ID rather than by name. OCSP_basic_sign_ctx() also signs OCSP response brsp but uses the parameters contained in digest context ctx.

"},{"location":"man3/OCSP_response_status/#return-values","title":"RETURN VALUES","text":"

OCSP_RESPONSE_status() returns a status value.

OCSP_response_get1_basic() returns an OCSP_BASICRESP structure pointer or NULL if an error occurred.

OCSP_response_create() returns an OCSP_RESPONSE structure pointer or NULL if an error occurred.

OCSP_RESPONSE_free() does not return a value.

OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key(), OCSP_basic_sign(), and OCSP_basic_sign_ctx() return 1 on success or 0 on failure.

OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match or 0 otherwise.

"},{"location":"man3/OCSP_response_status/#notes","title":"NOTES","text":"

OCSP_response_get1_basic() is only called if the status of a response is OCSP_RESPONSE_STATUS_SUCCESSFUL.

"},{"location":"man3/OCSP_response_status/#see-also","title":"SEE ALSO","text":"

crypto(7) OCSP_cert_to_id(3) OCSP_request_add1_nonce(3) OCSP_REQUEST_new(3) OCSP_resp_find_status(3) OCSP_sendreq_new(3) OCSP_RESPID_new(3) OCSP_RESPID_free(3)

"},{"location":"man3/OCSP_response_status/#history","title":"HISTORY","text":"

The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match() functions were added in OpenSSL 1.1.0a.

The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1.

"},{"location":"man3/OCSP_response_status/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/OCSP_sendreq_new/","title":"OCSP_sendreq_new","text":""},{"location":"man3/OCSP_sendreq_new/#name","title":"NAME","text":"

OCSP_REQ_CTX, OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_sendreq_bio, OCSP_REQ_CTX_i2d, OCSP_REQ_CTX_add1_header, OCSP_REQ_CTX_free, OCSP_set_max_response_length, OCSP_REQ_CTX_set1_req - OCSP responder query functions

"},{"location":"man3/OCSP_sendreq_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ocsp.h>\n\nOSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path,\n                                    const OCSP_REQUEST *req, int buf_size);\nOCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

typedef OSSL_HTTP_REQ_CTX OCSP_REQ_CTX;\nint OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx);\nint OCSP_REQ_CTX_i2d(OCSP_REQ_CT *rctx, const ASN1_ITEM *it, ASN1_VALUE *req);\nint OCSP_REQ_CTX_add1_header(OCSP_REQ_CT *rctx,\n                             const char *name, const char *value);\nvoid OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);\nvoid OCSP_set_max_response_length(OCSP_REQ_CT *rctx, unsigned long len);\nint OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req);\n
"},{"location":"man3/OCSP_sendreq_new/#description","title":"DESCRIPTION","text":"

These functions perform an OCSP POST request / response transfer over HTTP, using the HTTP request functions described in OSSL_HTTP_REQ_CTX(3).

The function OCSP_sendreq_new() builds a complete OSSL_HTTP_REQ_CTX structure with the BIO io to be used for requests and response, the URL path path, optionally the OCSP request req, and a response header maximum line length of buf_size. If buf_size is zero a default value of 4KiB is used. The req may be set to NULL and provided later using OCSP_REQ_CTX_set1_req() or OSSL_HTTP_REQ_CTX_set1_req(3). The io and path arguments to OCSP_sendreq_new() correspond to the components of the URL. For example if the responder URL is http://example.com/ocspreq the BIO io should haven been connected to host example.com on port 80 and path should be set to /ocspreq.

OCSP_sendreq_nbio() attempts to send the request prepared in rctx and to gather the response via HTTP, using the BIO io and path that were given when calling OCSP_sendreq_new(). If the operation gets completed it assigns the response, a pointer to a OCSP_RESPONSE structure, in *presp. The function may need to be called again if its result is -1, which indicates BIO_should_retry(3). In such a case it is advisable to sleep a little in between, using BIO_wait(3) on the read BIO to prevent a busy loop.

OCSP_sendreq_bio() combines OCSP_sendreq_new() with as many calls of OCSP_sendreq_nbio() as needed and then OCSP_REQ_CTX_free(), with a response header maximum line length 4k. It waits indefinitely on a response. It does not support setting a timeout or adding headers and is retained for compatibility; use OSSL_HTTP_transfer(3) instead.

OCSP_REQ_CTX_i2d(rctx, it, req) is equivalent to the following:

OSSL_HTTP_REQ_CTX_set1_req(rctx, \"application/ocsp-request\", it, req)\n

OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following:

OSSL_HTTP_REQ_CTX_set1_req(rctx, \"application/ocsp-request\",\n                           ASN1_ITEM_rptr(OCSP_REQUEST),\n                           (const ASN1_VALUE *)req)\n

The deprecated type and the remaining deprecated functions have been superseded by the following equivalents: OCSP_REQ_CTX by OSSL_HTTP_REQ_CTX(3), OCSP_REQ_CTX_add1_header() by OSSL_HTTP_REQ_CTX_add1_header(3), OCSP_REQ_CTX_free() by OSSL_HTTP_REQ_CTX_free(3), and OCSP_set_max_response_length() by OSSL_HTTP_REQ_CTX_set_max_response_length(3).

"},{"location":"man3/OCSP_sendreq_new/#return-values","title":"RETURN VALUES","text":"

OCSP_sendreq_new() returns a valid OSSL_HTTP_REQ_CTX structure or NULL if an error occurred.

OCSP_sendreq_nbio() returns 1 for success, 0 on error, -1 if retry is needed.

OCSP_sendreq_bio() returns the OCSP_RESPONSE structure sent by the responder or NULL if an error occurred.

"},{"location":"man3/OCSP_sendreq_new/#see-also","title":"SEE ALSO","text":"

OSSL_HTTP_REQ_CTX(3), OSSL_HTTP_transfer(3), OCSP_cert_to_id(3), OCSP_request_add1_nonce(3), OCSP_REQUEST_new(3), OCSP_resp_find_status(3), OCSP_response_status(3)

"},{"location":"man3/OCSP_sendreq_new/#history","title":"HISTORY","text":"

OCSP_REQ_CTX, OCSP_REQ_CTX_i2d(), OCSP_REQ_CTX_add1_header(), OCSP_REQ_CTX_free(), OCSP_set_max_response_length(), and OCSP_REQ_CTX_set1_req() were deprecated in OpenSSL 3.0.

"},{"location":"man3/OCSP_sendreq_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2022 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.

"},{"location":"man3/OPENSSL_Applink/","title":"OPENSSL_Applink","text":""},{"location":"man3/OPENSSL_Applink/#name","title":"NAME","text":"

OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time

"},{"location":"man3/OPENSSL_Applink/#synopsis","title":"SYNOPSIS","text":"
__declspec(dllexport) void **OPENSSL_Applink();\n
"},{"location":"man3/OPENSSL_Applink/#description","title":"DESCRIPTION","text":"

OPENSSL_Applink is application-side interface which provides a glue between OpenSSL BIO layer and Win32 compiler run-time environment. Even though it appears at application side, it's essentially OpenSSL private interface. For this reason application developers are not expected to implement it, but to compile provided module with compiler of their choice and link it into the target application. The referred module is available as applink.c, located alongside the public header files (only on the platforms where applicable).

"},{"location":"man3/OPENSSL_Applink/#return-values","title":"RETURN VALUES","text":"

Not available.

"},{"location":"man3/OPENSSL_Applink/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2018 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.

"},{"location":"man3/OPENSSL_FILE/","title":"OPENSSL_FILE","text":""},{"location":"man3/OPENSSL_FILE/#name","title":"NAME","text":"

OPENSSL_FILE, OPENSSL_LINE, OPENSSL_FUNC, OPENSSL_MSTR, OPENSSL_MSTR_HELPER - generic C programming utility macros

"},{"location":"man3/OPENSSL_FILE/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/macros.h>\n\n#define OPENSSL_FILE /* typically: __FILE__ */\n#define OPENSSL_LINE /* typically: __LINE__ */\n#define OPENSSL_FUNC /* typically: __func__ */\n\n#define OPENSSL_MSTR_HELPER(x) #x\n#define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)\n
"},{"location":"man3/OPENSSL_FILE/#description","title":"DESCRIPTION","text":"

The macros OPENSSL_FILE and OPENSSL_LINE typically yield the current filename and line number during C compilation. When OPENSSL_NO_FILENAMES is defined they yield \"\" and 0, respectively.

The macro OPENSSL_FUNC attempts to yield the name of the C function currently being compiled, as far as language and compiler versions allow. Otherwise, it yields \"(unknown function)\".

The macro OPENSSL_MSTR yields the expansion of the macro given as argument, which is useful for concatenation with string constants. The macro OPENSSL_MSTR_HELPER is an auxiliary macro for this purpose.

"},{"location":"man3/OPENSSL_FILE/#return-values","title":"RETURN VALUES","text":"

see above

"},{"location":"man3/OPENSSL_FILE/#see-also","title":"SEE ALSO","text":"

crypto(7)

"},{"location":"man3/OPENSSL_FILE/#history","title":"HISTORY","text":"

OPENSSL_FUNC, OPENSSL_MSTR, and OPENSSL_MSTR_HELPER were added in OpenSSL 3.0.

"},{"location":"man3/OPENSSL_FILE/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OPENSSL_LH_COMPFUNC/","title":"OPENSSL_LH_COMPFUNC","text":""},{"location":"man3/OPENSSL_LH_COMPFUNC/#name","title":"NAME","text":"

LHASH, LHASH_OF, DEFINE_LHASH_OF_EX, DEFINE_LHASH_OF, OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, LHASH_DOALL_ARG_FN_TYPE, IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush, lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_num_items, lh_TYPE_get_down_load, lh_TYPE_set_down_load, lh_TYPE_error, OPENSSL_LH_new, OPENSSL_LH_free, OPENSSL_LH_flush, OPENSSL_LH_insert, OPENSSL_LH_delete, OPENSSL_LH_retrieve, OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_doall_arg_thunk, OPENSSL_LH_set_thunks, OPENSSL_LH_num_items, OPENSSL_LH_get_down_load, OPENSSL_LH_set_down_load, OPENSSL_LH_error - dynamic hash table

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/lhash.h>\n\nLHASH_OF(TYPE)\n\nDEFINE_LHASH_OF_EX(TYPE);\n\nLHASH_OF(TYPE) *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);\nvoid lh_TYPE_free(LHASH_OF(TYPE) *table);\nvoid lh_TYPE_flush(LHASH_OF(TYPE) *table);\nOPENSSL_LHASH *OPENSSL_LH_set_thunks(OPENSSL_LHASH *lh,\n                                     OPENSSL_LH_HASHFUNCTHUNK hw,\n                                     OPENSSL_LH_COMPFUNCTHUNK cw,\n                                     OPENSSL_LH_DOALL_FUNC_THUNK daw,\n                                     OPENSSL_LH_DOALL_FUNCARG_THUNK daaw)\n\nTYPE *lh_TYPE_insert(LHASH_OF(TYPE) *table, TYPE *data);\nTYPE *lh_TYPE_delete(LHASH_OF(TYPE) *table, TYPE *data);\nTYPE *lh_TYPE_retrieve(LHASH_OF(TYPE) *table, TYPE *data);\n\nvoid lh_TYPE_doall(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNC func);\nvoid lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func,\n                       TYPE *arg);\nvoid OPENSSL_LH_doall_arg_thunk(OPENSSL_LHASH *lh,\n                                OPENSSL_LH_DOALL_FUNCARG_THUNK daaw,\n                                OPENSSL_LH_DOALL_FUNCARG fn, void *arg)\n\nunsigned long lh_TYPE_num_items(OPENSSL_LHASH *lh);\nunsigned long lh_TYPE_get_down_load(OPENSSL_LHASH *lh);\nvoid lh_TYPE_set_down_load(OPENSSL_LHASH *lh, unsigned long dl);\n\nint lh_TYPE_error(LHASH_OF(TYPE) *table);\n\ntypedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *);\ntypedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *);\ntypedef void (*OPENSSL_LH_DOALL_FUNC)(const void *);\ntypedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);\n\nOPENSSL_LHASH *OPENSSL_LH_new(OPENSSL_LH_HASHFUNC h, OPENSSL_LH_COMPFUNC c);\nvoid OPENSSL_LH_free(OPENSSL_LHASH *lh);\nvoid OPENSSL_LH_flush(OPENSSL_LHASH *lh);\n\nvoid *OPENSSL_LH_insert(OPENSSL_LHASH *lh, void *data);\nvoid *OPENSSL_LH_delete(OPENSSL_LHASH *lh, const void *data);\nvoid *OPENSSL_LH_retrieve(OPENSSL_LHASH *lh, const void *data);\n\nvoid OPENSSL_LH_doall(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNC func);\nvoid OPENSSL_LH_doall_arg(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNCARG func, void *arg);\n\nunsigned long OPENSSL_LH_num_items(OPENSSL_LHASH *lh);\nunsigned long OPENSSL_LH_get_down_load(OPENSSL_LHASH *lh);\nvoid OPENSSL_LH_set_down_load(OPENSSL_LHASH *lh, unsigned long dl);\n\nint OPENSSL_LH_error(OPENSSL_LHASH *lh);\n\n#define LH_LOAD_MULT   /* integer constant */\n

The following macro is deprecated:

DEFINE_LHASH_OF(TYPE);\n
"},{"location":"man3/OPENSSL_LH_COMPFUNC/#description","title":"DESCRIPTION","text":"

This library implements type-checked dynamic hash tables. The hash table entries can be arbitrary structures. Usually they consist of key and value fields. In the description here, TYPE is used a placeholder for any of the OpenSSL datatypes, such as SSL_SESSION.

To define a new type-checked dynamic hash table, use DEFINE_LHASH_OF_EX(). DEFINE_LHASH_OF() was previously used for this purpose, but is now deprecated. The DEFINE_LHASH_OF_EX() macro provides all functionality of DEFINE_LHASH_OF() except for certain deprecated statistics functions (see OPENSSL_LH_stats(3)).

lh_TYPE_new() creates a new LHASH_OF(TYPE) structure to store arbitrary data entries, and specifies the 'hash' and 'compare' callbacks to be used in organising the table's entries. The hash callback takes a pointer to a table entry as its argument and returns an unsigned long hash value for its key field. The hash value is normally truncated to a power of 2, so make sure that your hash function returns well mixed low order bits. The compare callback takes two arguments (pointers to two hash table entries), and returns 0 if their keys are equal, nonzero otherwise.

If your hash table will contain items of some particular type and the hash and compare callbacks hash/compare these types, then the IMPLEMENT_LHASH_HASH_FN and IMPLEMENT_LHASH_COMP_FN macros can be used to create callback wrappers of the prototypes required by lh_TYPE_new() as shown in this example:

/*\n * Implement the hash and compare functions; \"stuff\" can be any word.\n */\nstatic unsigned long stuff_hash(const TYPE *a)\n{\n    ...\n}\nstatic int stuff_cmp(const TYPE *a, const TYPE *b)\n{\n    ...\n}\n\n/*\n * Implement the wrapper functions.\n */\nstatic IMPLEMENT_LHASH_HASH_FN(stuff, TYPE)\nstatic IMPLEMENT_LHASH_COMP_FN(stuff, TYPE)\n

If the type is going to be used in several places, the following macros can be used in a common header file to declare the function wrappers:

DECLARE_LHASH_HASH_FN(stuff, TYPE)\nDECLARE_LHASH_COMP_FN(stuff, TYPE)\n

Then a hash table of TYPE objects can be created using this:

LHASH_OF(TYPE) *htable;\n\nhtable = B<lh_I<TYPE>_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));\n

lh_TYPE_free() frees the LHASH_OF(TYPE) structure table. Allocated hash table entries will not be freed; consider using lh_TYPE_doall() to deallocate any remaining entries in the hash table (see below). If the argument is NULL, nothing is done.

lh_TYPE_flush() empties the LHASH_OF(TYPE) structure table. New entries can be added to the flushed table. Allocated hash table entries will not be freed; consider using lh_TYPE_doall() to deallocate any remaining entries in the hash table (see below).

lh_TYPE_insert() inserts the structure pointed to by data into table. If there already is an entry with the same key, the old value is replaced. Note that lh_TYPE_insert() stores pointers, the data are not copied.

lh_TYPE_delete() deletes an entry from table.

lh_TYPE_retrieve() looks up an entry in table. Normally, data is a structure with the key field(s) set; the function will return a pointer to a fully populated structure.

lh_TYPE_doall() will, for every entry in the hash table, call func with the data item as its parameter. For example:

/* Cleans up resources belonging to 'a' (this is implemented elsewhere) */\nvoid TYPE_cleanup_doall(TYPE *a);\n\n/* Implement a prototype-compatible wrapper for \"TYPE_cleanup\" */\nIMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE)\n\n/* Call \"TYPE_cleanup\" against all items in a hash table. */\nlh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup));\n\n/* Then the hash table itself can be deallocated */\nlh_TYPE_free(hashtable);\n

lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that func will be called with arg as the second argument and func should be of type LHASH_DOALL_ARG_FN(TYPE) (a callback prototype that is passed both the table entry and an extra argument). As with lh_doall(), you can instead choose to declare your callback with a prototype matching the types you are dealing with and use the declare/implement macros to create compatible wrappers that cast variables before calling your type-specific callbacks. An example of this is demonstrated here (printing all hash table entries to a BIO that is provided by the caller):

/* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */\nvoid TYPE_print_doall_arg(const TYPE *a, BIO *output_bio);\n\n/* Implement a prototype-compatible wrapper for \"TYPE_print\" */\nstatic IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO)\n\n/* Print out the entire hashtable to a particular BIO */\nlh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO,\n                  logging_bio);\n

Note that it is by default not safe to use lh_TYPE_delete() inside a callback passed to lh_TYPE_doall() or lh_TYPE_doall_arg(). The reason for this is that deleting an item from the hash table may result in the hash table being contracted to a smaller size and rehashed. lh_TYPE_doall() and lh_TYPE_doall_arg() are unsafe and will exhibit undefined behaviour under these conditions, as these functions assume the hash table size and bucket pointers do not change during the call.

If it is desired to use lh_TYPE_doall() or lh_TYPE_doall_arg() with lh_TYPE_delete(), it is essential that you call lh_TYPE_set_down_load() with a down_load argument of 0 first. This disables hash table contraction and guarantees that it will be safe to delete items from a hash table during a call to lh_TYPE_doall() or lh_TYPE_doall_arg().

It is never safe to call lh_TYPE_insert() during a call to lh_TYPE_doall() or lh_TYPE_doall_arg().

lh_TYPE_error() can be used to determine if an error occurred in the last operation.

lh_TYPE_num_items() returns the number of items in the hash table.

lh_TYPE_get_down_load() and lh_TYPE_set_down_load() get and set the factor used to determine when the hash table is contracted. The factor is the load factor at or below which hash table contraction will occur, multiplied by LH_LOAD_MULT, where the load factor is the number of items divided by the number of nodes. Setting this value to 0 disables hash table contraction.

OPENSSL_LH_new() is the same as the lh_TYPE_new() except that it is not type specific. So instead of returning an LHASH_OF(TYPE) value it returns a void *. In the same way the functions OPENSSL_LH_free(), OPENSSL_LH_flush(), OPENSSL_LH_insert(), OPENSSL_LH_delete(), OPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(), OPENSSL_LH_num_items(), OPENSSL_LH_get_down_load(), OPENSSL_LH_set_down_load() and OPENSSL_LH_error() are equivalent to the similarly named lh_TYPE functions except that they return or use a void * where the equivalent lh_TYPE function returns or uses a TYPE * or LHASH_OF(TYPE) *. lh_TYPE functions are implemented as type checked wrappers around the OPENSSL_LH functions. Most applications should not call the OPENSSL_LH functions directly.

OPENSSL_LH_set_thunks() and OPENSSL_LH_doall_arg_thunk(), while public by necessity, are actually internal functions and should not be used.

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#return-values","title":"RETURN VALUES","text":"

lh_TYPE_new() and OPENSSL_LH_new() return NULL on error, otherwise a pointer to the new LHASH structure.

When a hash table entry is replaced, lh_TYPE_insert() or OPENSSL_LH_insert() return the value being replaced. NULL is returned on normal operation and on error.

lh_TYPE_delete() and OPENSSL_LH_delete() return the entry being deleted. NULL is returned if there is no such value in the hash table.

lh_TYPE_retrieve() and OPENSSL_LH_retrieve() return the hash table entry if it has been found, NULL otherwise.

lh_TYPE_error() and OPENSSL_LH_error() return 1 if an error occurred in the last operation, 0 otherwise. It's meaningful only after non-retrieve operations.

lh_TYPE_free(), OPENSSL_LH_free(), lh_TYPE_flush(), OPENSSL_LH_flush(), lh_TYPE_doall() OPENSSL_LH_doall(), lh_TYPE_doall_arg() and OPENSSL_LH_doall_arg() return no values.

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#note","title":"NOTE","text":"

The LHASH code is not thread safe. All updating operations, as well as lh_TYPE_error() or OPENSSL_LH_error() calls must be performed under a write lock. All retrieve operations should be performed under a read lock, unless accurate usage statistics are desired. In which case, a write lock should be used for retrieve operations as well. For output of the usage statistics, using the functions from OPENSSL_LH_stats(3), a read lock suffices.

The LHASH code regards table entries as constant data. As such, it internally represents lh_insert()'d items with a \"const void *\" pointer type. This is why callbacks such as those used by lh_doall() and lh_doall_arg() declare their prototypes with \"const\", even for the parameters that pass back the table items' data pointers - for consistency, user-provided data is \"const\" at all times as far as the LHASH code is concerned. However, as callers are themselves providing these pointers, they can choose whether they too should be treating all such parameters as constant.

As an example, a hash table may be maintained by code that, for reasons of encapsulation, has only \"const\" access to the data being indexed in the hash table (i.e. it is returned as \"const\" from elsewhere in their code) - in this case the LHASH prototypes are appropriate as-is. Conversely, if the caller is responsible for the life-time of the data in question, then they may well wish to make modifications to table item passed back in the lh_doall() or lh_doall_arg() callbacks (see the \"TYPE_cleanup\" example above). If so, the caller can either cast the \"const\" away (if they're providing the raw callbacks themselves) or use the macros to declare/implement the wrapper functions without \"const\" types.

Callers that only have \"const\" access to data they're indexing in a table, yet declare callbacks without constant types (or cast the \"const\" away themselves), are therefore creating their own risks/bugs without being encouraged to do so by the API. On a related note, those auditing code should pay special attention to any instances of DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types without any \"const\" qualifiers.

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#bugs","title":"BUGS","text":"

lh_TYPE_insert() and OPENSSL_LH_insert() return NULL both for success and error.

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#see-also","title":"SEE ALSO","text":"

OPENSSL_LH_stats(3)

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#history","title":"HISTORY","text":"

In OpenSSL 1.0.0, the lhash interface was revamped for better type checking.

In OpenSSL 3.1, DEFINE_LHASH_OF_EX() was introduced and DEFINE_LHASH_OF() was deprecated.

"},{"location":"man3/OPENSSL_LH_COMPFUNC/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 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.

"},{"location":"man3/OPENSSL_LH_stats/","title":"OPENSSL_LH_stats","text":""},{"location":"man3/OPENSSL_LH_stats/#name","title":"NAME","text":"

OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats, OPENSSL_LH_stats_bio, OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics

"},{"location":"man3/OPENSSL_LH_stats/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/lhash.h>\n

The following functions have been deprecated since OpenSSL 3.1, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void OPENSSL_LH_node_stats(LHASH *table, FILE *out);\nvoid OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out);\n\nvoid OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out);\nvoid OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out);\n\nvoid OPENSSL_LH_stats(LHASH *table, FILE *out);\nvoid OPENSSL_LH_stats_bio(LHASH *table, BIO *out);\n
"},{"location":"man3/OPENSSL_LH_stats/#description","title":"DESCRIPTION","text":"

The LHASH structure records statistics about most aspects of accessing the hash table.

OPENSSL_LH_stats() prints out statistics on the size of the hash table and how many entries are in it. For historical reasons, this function also outputs a number of additional statistics, but the tracking of these statistics is no longer supported and these statistics are always reported as zero.

OPENSSL_LH_node_stats() prints the number of entries for each 'bucket' in the hash table.

OPENSSL_LH_node_usage_stats() prints out a short summary of the state of the hash table. It prints the 'load' and the 'actual load'. The load is the average number of data items per 'bucket' in the hash table. The 'actual load' is the average number of items per 'bucket', but only for buckets which contain entries. So the 'actual load' is the average number of searches that will need to find an item in the hash table, while the 'load' is the average number that will be done to record a miss.

OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio() are the same as the above, except that the output goes to a BIO.

These functions are deprecated and should no longer be used.

"},{"location":"man3/OPENSSL_LH_stats/#return-values","title":"RETURN VALUES","text":"

These functions do not return values.

"},{"location":"man3/OPENSSL_LH_stats/#note","title":"NOTE","text":"

These calls should be made under a read lock. Refer to \"NOTE\" in OPENSSL_LH_COMPFUNC(3) for more details about the locks required when using the LHASH data structure.

"},{"location":"man3/OPENSSL_LH_stats/#see-also","title":"SEE ALSO","text":"

bio(7), OPENSSL_LH_COMPFUNC(3)

"},{"location":"man3/OPENSSL_LH_stats/#history","title":"HISTORY","text":"

These functions were deprecated in version 3.1.

"},{"location":"man3/OPENSSL_LH_stats/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 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.

"},{"location":"man3/OPENSSL_config/","title":"OPENSSL_config","text":""},{"location":"man3/OPENSSL_config/#name","title":"NAME","text":"

OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions

"},{"location":"man3/OPENSSL_config/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n

The following functions have been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void OPENSSL_config(const char *appname);\nvoid OPENSSL_no_config(void);\n
"},{"location":"man3/OPENSSL_config/#description","title":"DESCRIPTION","text":"

OPENSSL_config() configures OpenSSL using the standard openssl.cnf and reads from the application section appname. If appname is NULL then the default section, openssl_conf, will be used. Errors are silently ignored. Multiple calls have no effect.

OPENSSL_no_config() disables configuration. If called before OPENSSL_config() no configuration takes place.

If the application is built with OPENSSL_LOAD_CONF defined, then a call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config() first.

"},{"location":"man3/OPENSSL_config/#notes","title":"NOTES","text":"

The OPENSSL_config() function is designed to be a very simple \"call it and forget it\" function. It is however much better than nothing. Applications which need finer control over their configuration functionality should use the configuration functions such as CONF_modules_load() directly. This function is deprecated and its use should be avoided. Applications should instead call CONF_modules_load() during initialization (that is before starting any threads).

There are several reasons why calling the OpenSSL configuration routines is advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs). However, very few applications currently support the control interface and so very few can load and use dynamic ENGINEs. Equally in future more sophisticated ENGINEs will require certain control operations to customize them. If an application calls OPENSSL_config() it doesn't need to know or care about ENGINE control operations because they can be performed by editing a configuration file.

"},{"location":"man3/OPENSSL_config/#environment","title":"ENVIRONMENT","text":""},{"location":"man3/OPENSSL_config/#return-values","title":"RETURN VALUES","text":"

Neither OPENSSL_config() nor OPENSSL_no_config() return a value.

"},{"location":"man3/OPENSSL_config/#see-also","title":"SEE ALSO","text":"

config(5), CONF_modules_load_file(3)

"},{"location":"man3/OPENSSL_config/#history","title":"HISTORY","text":"

The OPENSSL_no_config() and OPENSSL_config() functions were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().

"},{"location":"man3/OPENSSL_config/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/OPENSSL_fork_prepare/","title":"OPENSSL_fork_prepare","text":""},{"location":"man3/OPENSSL_fork_prepare/#name","title":"NAME","text":"

OPENSSL_fork_prepare, OPENSSL_fork_parent, OPENSSL_fork_child - OpenSSL fork handlers

"},{"location":"man3/OPENSSL_fork_prepare/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void OPENSSL_fork_prepare(void);\nvoid OPENSSL_fork_parent(void);\nvoid OPENSSL_fork_child(void);\n
"},{"location":"man3/OPENSSL_fork_prepare/#description","title":"DESCRIPTION","text":"

These methods are currently unused, and as such, no replacement methods are required or planned.

OpenSSL has state that should be reset when a process forks. For example, the entropy pool used to generate random numbers (and therefore encryption keys) should not be shared across multiple programs. The OPENSSL_fork_prepare(), OPENSSL_fork_parent(), and OPENSSL_fork_child() functions are used to reset this internal state.

Platforms without fork(2) will probably not need to use these functions. Platforms with fork(2) but without pthread_atfork(3) will probably need to call them manually, as described in the following paragraph. Platforms such as Linux that have both functions will normally not need to call these functions as the OpenSSL library will do so automatically.

OPENSSL_init_crypto(3) will register these functions with the appropriate handler, when the OPENSSL_INIT_ATFORK flag is used. For other applications, these functions can be called directly. They should be used according to the calling sequence described by the pthread_atfork(3) documentation, which is summarized here. OPENSSL_fork_prepare() should be called before a fork() is done. After the fork() returns, the parent process should call OPENSSL_fork_parent() and the child process should call OPENSSL_fork_child().

"},{"location":"man3/OPENSSL_fork_prepare/#return-values","title":"RETURN VALUES","text":"

OPENSSL_fork_prepare(), OPENSSL_fork_parent() and OPENSSL_fork_child() do not return values.

"},{"location":"man3/OPENSSL_fork_prepare/#see-also","title":"SEE ALSO","text":"

OPENSSL_init_crypto(3)

"},{"location":"man3/OPENSSL_fork_prepare/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 1.1.1.

"},{"location":"man3/OPENSSL_fork_prepare/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/OPENSSL_gmtime/","title":"OPENSSL_gmtime","text":""},{"location":"man3/OPENSSL_gmtime/#name","title":"NAME","text":"

OPENSSL_gmtime, OPENSSL_gmtime_adj, OPENSSL_gmtime_diff - platform-agnostic OpenSSL time routines

"},{"location":"man3/OPENSSL_gmtime/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nstruct tm *OPENSSL_gmtime(const time_t *timer, struct tm *result);\nint OPENSSL_gmtime_adj(struct tm *tm, int offset_day, long offset_sec);\nint OPENSSL_gmtime_diff(int *pday, int *psec,\n                       const struct tm *from, const struct tm *to);\n
"},{"location":"man3/OPENSSL_gmtime/#description","title":"DESCRIPTION","text":"

OPENSSL_gmtime() returns the UTC time specified by timer into the provided result argument.

OPENSSL_gmtime_adj() adds the offsets in offset_day and offset_sec to tm.

OPENSSL_gmtime_diff() calculates the difference between from and to.

"},{"location":"man3/OPENSSL_gmtime/#notes","title":"NOTES","text":"

It is an error to call OPENSSL_gmtime() with result equal to NULL. The contents of the time_t given by timer are stored into the result. Calling with timer equal to NULL means use the current time.

OPENSSL_gmtime_adj() converts tm into a days and seconds value, adds the offsets, then converts back into a struct tm specified by tm. Leap seconds are not considered.

OPENSSL_gmtime_diff() calculates the difference between the two struct tm structures from and to. The difference in days is placed into *pday, the remaining seconds are placed to *psec. The value in *psec will be less than the number of seconds per day (3600). Leap seconds are not considered.

"},{"location":"man3/OPENSSL_gmtime/#return-values","title":"RETURN VALUES","text":"

OPENSSL_gmtime() returns NULL on error, or result on success.

OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() return 0 on error, and 1 on success.

"},{"location":"man3/OPENSSL_gmtime/#history","title":"HISTORY","text":"

OPENSSL_gmtime(), OPENSSL_gmtime_adj() and OPENSSL_gmtime_diff() have been in OpenSSL since 1.0.0.

"},{"location":"man3/OPENSSL_gmtime/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OPENSSL_hexchar2int/","title":"OPENSSL_hexchar2int","text":""},{"location":"man3/OPENSSL_hexchar2int/#name","title":"NAME","text":"

OPENSSL_hexchar2int, OPENSSL_hexstr2buf_ex, OPENSSL_hexstr2buf, OPENSSL_buf2hexstr_ex, OPENSSL_buf2hexstr - Hex encoding and decoding functions

"},{"location":"man3/OPENSSL_hexchar2int/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint OPENSSL_hexchar2int(unsigned char c);\nint OPENSSL_hexstr2buf_ex(unsigned char *buf, size_t buf_n, long *buflen,\n                          const char *str, const char sep);\nunsigned char *OPENSSL_hexstr2buf(const char *str, long *len);\nint OPENSSL_buf2hexstr_ex(char *str, size_t str_n, size_t *strlength,\n                          const unsigned char *buf, long buflen,\n                          const char sep);\nchar *OPENSSL_buf2hexstr(const unsigned char *buf, long buflen);\n
"},{"location":"man3/OPENSSL_hexchar2int/#description","title":"DESCRIPTION","text":"

OPENSSL_hexchar2int() converts a hexadecimal character to its numeric equivalent.

OPENSSL_hexstr2buf_ex() decodes the hex string str and places the resulting string of bytes in the given buf. The character sep is the separator between the bytes, setting this to '\\0' means that there is no separator. buf_n gives the size of the buffer. If buflen is not NULL, it is filled in with the result length. To find out how large the result will be, call this function with NULL for buf. Colons between two-character hex \"bytes\" are accepted and ignored. An odd number of hex digits is an error.

OPENSSL_hexstr2buf() does the same thing as OPENSSL_hexstr2buf_ex(), but allocates the space for the result, and returns the result. It uses a default separator of ':'. The memory is allocated by calling OPENSSL_malloc() and should be released by calling OPENSSL_free().

OPENSSL_buf2hexstr_ex() encodes the contents of the given buf with length buflen and places the resulting hexadecimal character string in the given str. The character sep is the separator between the bytes, setting this to '\\0' means that there is no separator. str_n gives the size of the of the string buffer. If strlength is not NULL, it is filled in with the result length. To find out how large the result will be, call this function with NULL for str.

OPENSSL_buf2hexstr() does the same thing as OPENSSL_buf2hexstr_ex(), but allocates the space for the result, and returns the result. It uses a default separator of ':'. The memory is allocated by calling OPENSSL_malloc() and should be released by calling OPENSSL_free().

"},{"location":"man3/OPENSSL_hexchar2int/#return-values","title":"RETURN VALUES","text":"

OPENSSL_hexchar2int returns the value of a decoded hex character, or -1 on error.

OPENSSL_buf2hexstr() and OPENSSL_hexstr2buf() return a pointer to allocated memory, or NULL on error.

OPENSSL_buf2hexstr_ex() and OPENSSL_hexstr2buf_ex() return 1 on success, or 0 on error.

"},{"location":"man3/OPENSSL_hexchar2int/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2022 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.

"},{"location":"man3/OPENSSL_ia32cap/","title":"OPENSSL_ia32cap","text":""},{"location":"man3/OPENSSL_ia32cap/#name","title":"NAME","text":"

OPENSSL_ia32cap - the x86[_64] processor capabilities vector

"},{"location":"man3/OPENSSL_ia32cap/#synopsis","title":"SYNOPSIS","text":"
env OPENSSL_ia32cap=... <application>\n
"},{"location":"man3/OPENSSL_ia32cap/#description","title":"DESCRIPTION","text":"

OpenSSL supports a range of x86[_64] instruction set extensions. These extensions are denoted by individual bits in capability vector returned by processor in EDX:ECX register pair after executing CPUID instruction with EAX=1 input value (see Intel Application Note #241618). This vector is copied to memory upon toolkit initialization and used to choose between different code paths to provide optimal performance across wide range of processors. For the moment of this writing following bits are significant:

For example, in 32-bit application context clearing bit #26 at run-time disables high-performance SSE2 code present in the crypto library, while clearing bit #24 disables SSE2 code operating on 128-bit XMM register bank. You might have to do the latter if target OpenSSL application is executed on SSE2 capable CPU, but under control of OS that does not enable XMM registers. Historically address of the capability vector copy was exposed to application through OPENSSL_ia32cap_loc(), but not anymore. Now the only way to affect the capability detection is to set OPENSSL_ia32cap environment variable prior target application start. To give a specific example, on Intel P4 processor env OPENSSL_ia32cap=0x16980010 apps/openssl, or better yet env OPENSSL_ia32cap=~0x1000000 apps/openssl would achieve the desired effect. Alternatively you can reconfigure the toolkit with no-sse2 option and recompile.

Less intuitive is clearing bit #28, or ~0x10000000 in the \"environment variable\" terms. The truth is that it's not copied from CPUID output verbatim, but is adjusted to reflect whether or not the data cache is actually shared between logical cores. This in turn affects the decision on whether or not expensive countermeasures against cache-timing attacks are applied, most notably in AES assembler module.

The capability vector is further extended with EBX value returned by CPUID with EAX=7 and ECX=0 as input. Following bits are significant:

To control this extended capability word use : as delimiter when setting up OPENSSL_ia32cap environment variable. For example assigning :~0x20 would disable AVX2 code paths, and :0 - all post-AVX extensions.

"},{"location":"man3/OPENSSL_ia32cap/#return-values","title":"RETURN VALUES","text":"

Not available.

"},{"location":"man3/OPENSSL_ia32cap/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2021 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.

"},{"location":"man3/OPENSSL_init_crypto/","title":"OPENSSL_init_crypto","text":""},{"location":"man3/OPENSSL_init_crypto/#name","title":"NAME","text":"

OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags, OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit, OPENSSL_thread_stop_ex, OPENSSL_thread_stop - OpenSSL initialisation and deinitialisation functions

"},{"location":"man3/OPENSSL_init_crypto/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nvoid OPENSSL_cleanup(void);\nint OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);\nint OPENSSL_atexit(void (*handler)(void));\nvoid OPENSSL_thread_stop_ex(OSSL_LIB_CTX *ctx);\nvoid OPENSSL_thread_stop(void);\n\nOPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);\nint OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *init,\n                                     const char* filename);\nint OPENSSL_INIT_set_config_file_flags(OPENSSL_INIT_SETTINGS *init,\n                                       unsigned long flags);\nint OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,\n                                    const char* name);\nvoid OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);\n
"},{"location":"man3/OPENSSL_init_crypto/#description","title":"DESCRIPTION","text":"

During normal operation OpenSSL (libcrypto) will allocate various resources at start up that must, subsequently, be freed on close down of the library. Additionally some resources are allocated on a per thread basis (if the application is multi-threaded), and these resources must be freed prior to the thread closing.

As of version 1.1.0 OpenSSL will automatically allocate all resources that it needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required.

However, there may be situations when explicit initialisation is desirable or needed, for example when some nondefault initialisation is required. The function OPENSSL_init_crypto() can be used for this purpose for libcrypto (see also OPENSSL_init_ssl(3) for the libssl equivalent).

Numerous internal OpenSSL functions call OPENSSL_init_crypto(). Therefore, in order to perform nondefault initialisation, OPENSSL_init_crypto() MUST be called by application code prior to any other OpenSSL function calls.

The opts parameter specifies which aspects of libcrypto should be initialised. Valid options are:

Multiple options may be combined together in a single call to OPENSSL_init_crypto(). For example:

OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS\n                    | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);\n

The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto and libssl). All resources allocated by OpenSSL are freed. Typically there should be no need to call this function directly as it is initiated automatically on application exit. This is done via the standard C library atexit() function. In the event that the application will close in a manner that will not call the registered atexit() handlers then the application should call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL are discouraged from calling this function and should instead, typically, rely on auto-deinitialisation. This is to avoid error conditions where both an application and a library it depends on both use OpenSSL, and the library deinitialises it before the application has finished using it.

Once OPENSSL_cleanup() has been called the library cannot be reinitialised. Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error will be added to the error stack. Note that because initialisation has failed OpenSSL error strings will not be available, only an error code. This code can be put through the openssl errstr command line application to produce a human readable error (see openssl-errstr(1)).

The OPENSSL_atexit() function enables the registration of a function to be called during OPENSSL_cleanup(). Stop handlers are called after deinitialisation of resources local to a thread, but before other process wide resources are freed. In the event that multiple stop handlers are registered, no guarantees are made about the order of execution.

The OPENSSL_thread_stop_ex() function deallocates resources associated with the current thread for the given OSSL_LIB_CTX ctx. The ctx parameter can be NULL in which case the default OSSL_LIB_CTX is used.

Typically, this function will be called automatically by the library when the thread exits as long as the OSSL_LIB_CTX has not been freed before the thread exits. If OSSL_LIB_CTX_free() is called OPENSSL_thread_stop_ex will be called automatically for the current thread (but not any other threads that may have used this OSSL_LIB_CTX).

OPENSSL_thread_stop_ex should be called on all threads that will exit after the OSSL_LIB_CTX is freed. Typically this is not necessary for the default OSSL_LIB_CTX (because all resources are cleaned up on library exit) except if thread local resources should be freed before library exit, or under the circumstances described in the NOTES section below.

OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the default OSSL_LIB_CTX is always used.

The OPENSSL_INIT_LOAD_CONFIG flag will load a configuration file, as with CONF_modules_load_file(3) with NULL filename and application name and the CONF_MFLAGS_IGNORE_MISSING_FILE, CONF_MFLAGS_IGNORE_RETURN_CODES and CONF_MFLAGS_DEFAULT_SECTION flags. The filename, application name, and flags can be customized by providing a non-null OPENSSL_INIT_SETTINGS object. The object can be allocated via OPENSSL_INIT_new(). The OPENSSL_INIT_set_config_filename() function can be used to specify a nondefault filename, which is copied and need not refer to persistent storage. Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a nondefault application name. Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags. If the CONF_MFLAGS_IGNORE_RETURN_CODES flag is not included, any errors in the configuration file will cause an error return from OPENSSL_init_crypto or indirectly OPENSSL_init_ssl(3). The object can be released with OPENSSL_INIT_free() when done. If the argument to OPENSSL_INIT_free() is NULL, nothing is done.

"},{"location":"man3/OPENSSL_init_crypto/#notes","title":"NOTES","text":"

Resources local to a thread are deallocated automatically when the thread exits (e.g. in a pthreads environment, when pthread_exit() is called). On Windows platforms this is done in response to a DLL_THREAD_DETACH message being sent to the libcrypto32.dll entry point. Some windows functions may cause threads to exit without sending this message (for example ExitProcess()). If the application uses such functions, then the application must free up OpenSSL resources directly via a call to OPENSSL_thread_stop() on each thread. Similarly this message will also not be sent if OpenSSL is linked statically, and therefore applications using static linking should also call OPENSSL_thread_stop() on each thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the threads are not destroyed until after FreeLibrary() is called then each thread should call OPENSSL_thread_stop() prior to the FreeLibrary() call.

On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is multi-threaded and if dlclose() is subsequently called prior to the threads being destroyed then OpenSSL will not be able to deallocate resources associated with those threads. The application should either call OPENSSL_thread_stop() on each thread prior to the dlclose() call, or alternatively the original dlopen() call should use the RTLD_NODELETE flag (where available on the platform).

"},{"location":"man3/OPENSSL_init_crypto/#return-values","title":"RETURN VALUES","text":"

The functions OPENSSL_init_crypto, OPENSSL_atexit() and OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.

"},{"location":"man3/OPENSSL_init_crypto/#see-also","title":"SEE ALSO","text":"

OPENSSL_init_ssl(3)

"},{"location":"man3/OPENSSL_init_crypto/#history","title":"HISTORY","text":"

The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname() and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.

"},{"location":"man3/OPENSSL_init_crypto/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/OPENSSL_init_ssl/","title":"OPENSSL_init_ssl","text":""},{"location":"man3/OPENSSL_init_ssl/#name","title":"NAME","text":"

OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation

"},{"location":"man3/OPENSSL_init_ssl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);\n
"},{"location":"man3/OPENSSL_init_ssl/#description","title":"DESCRIPTION","text":"

During normal operation OpenSSL (libssl and libcrypto) will allocate various resources at start up that must, subsequently, be freed on close down of the library. Additionally some resources are allocated on a per thread basis (if the application is multi-threaded), and these resources must be freed prior to the thread closing.

As of version 1.1.0 OpenSSL will automatically allocate all resources that it needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required.

However, there may be situations when explicit initialisation is desirable or needed, for example when some nondefault initialisation is required. The function OPENSSL_init_ssl() can be used for this purpose. Calling this function will explicitly initialise BOTH libcrypto and libssl. To explicitly initialise ONLY libcrypto see the OPENSSL_init_crypto(3) function.

Numerous internal OpenSSL functions call OPENSSL_init_ssl(). Therefore, in order to perform nondefault initialisation, OPENSSL_init_ssl() MUST be called by application code prior to any other OpenSSL function calls.

The opts parameter specifies which aspects of libssl and libcrypto should be initialised. Valid options for libcrypto are described on the OPENSSL_init_crypto(3) page. In addition to any libcrypto specific option the following libssl options can also be used:

OPENSSL_init_ssl() takes a settings parameter which can be used to set parameter values. See OPENSSL_init_crypto(3) for details.

"},{"location":"man3/OPENSSL_init_ssl/#return-values","title":"RETURN VALUES","text":"

The function OPENSSL_init_ssl() returns 1 on success or 0 on error.

"},{"location":"man3/OPENSSL_init_ssl/#see-also","title":"SEE ALSO","text":"

OPENSSL_init_crypto(3)

"},{"location":"man3/OPENSSL_init_ssl/#history","title":"HISTORY","text":"

The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0.

"},{"location":"man3/OPENSSL_init_ssl/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/OPENSSL_instrument_bus/","title":"OPENSSL_instrument_bus","text":""},{"location":"man3/OPENSSL_instrument_bus/#name","title":"NAME","text":"

OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus

"},{"location":"man3/OPENSSL_instrument_bus/#synopsis","title":"SYNOPSIS","text":"
#ifdef OPENSSL_CPUID_OBJ\nsize_t OPENSSL_instrument_bus(unsigned int *vector, size_t num);\nsize_t OPENSSL_instrument_bus2(unsigned int *vector, size_t num, size_t max);\n#endif\n
"},{"location":"man3/OPENSSL_instrument_bus/#description","title":"DESCRIPTION","text":"

It was empirically found that timings of references to primary memory are subject to irregular, apparently non-deterministic variations. The subroutines in question instrument these references for purposes of gathering randomness for random number generator. In order to make it bus-bound a 'flush cache line' instruction is used between probes. In addition probes are added to vector elements in atomic or interlocked manner, which should contribute additional noise on multi-processor systems. This also means that vector[num] should be zeroed upon invocation (if you want to retrieve actual probe values).

OPENSSL_instrument_bus() performs num probes and records the number of oscillator cycles every probe took.

OPENSSL_instrument_bus2() on the other hand accumulates consecutive probes with the same value, i.e. in a way it records duration of periods when probe values appeared deterministic. The subroutine performs at most max probes in attempt to fill the vector[num], with max value of 0 meaning \"as many as it takes.\"

"},{"location":"man3/OPENSSL_instrument_bus/#return-values","title":"RETURN VALUES","text":"

Return value of 0 indicates that CPU is not capable of performing the benchmark, either because oscillator counter or 'flush cache line' is not available on current platform. For reference, on x86 'flush cache line' was introduced with the SSE2 extensions.

Otherwise number of recorded values is returned.

"},{"location":"man3/OPENSSL_instrument_bus/#copyright","title":"COPYRIGHT","text":"

Copyright 2011-2018 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.

"},{"location":"man3/OPENSSL_load_builtin_modules/","title":"OPENSSL_load_builtin_modules","text":""},{"location":"man3/OPENSSL_load_builtin_modules/#name","title":"NAME","text":"

OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules

"},{"location":"man3/OPENSSL_load_builtin_modules/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\nvoid OPENSSL_load_builtin_modules(void);\nvoid ASN1_add_oid_module(void);\nvoid ENGINE_add_conf_module(void);\n
"},{"location":"man3/OPENSSL_load_builtin_modules/#description","title":"DESCRIPTION","text":"

The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL configuration modules to the internal list. They can then be used by the OpenSSL configuration code.

ASN1_add_oid_module() adds just the ASN1 OBJECT module.

ENGINE_add_conf_module() adds just the ENGINE configuration module.

"},{"location":"man3/OPENSSL_load_builtin_modules/#notes","title":"NOTES","text":"

If the simple configuration function OPENSSL_config() is called then OPENSSL_load_builtin_modules() is called automatically.

Applications which use the configuration functions directly will need to call OPENSSL_load_builtin_modules() themselves before any other configuration code.

Applications should call OPENSSL_load_builtin_modules() to load all configuration modules instead of adding modules selectively: otherwise functionality may be missing from the application if an when new modules are added.

"},{"location":"man3/OPENSSL_load_builtin_modules/#return-values","title":"RETURN VALUES","text":"

None of the functions return a value.

"},{"location":"man3/OPENSSL_load_builtin_modules/#see-also","title":"SEE ALSO","text":"

config(5), OPENSSL_config(3)

"},{"location":"man3/OPENSSL_load_builtin_modules/#history","title":"HISTORY","text":"

ENGINE_add_conf_module() was deprecated in OpenSSL 3.0.

"},{"location":"man3/OPENSSL_load_builtin_modules/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

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

"},{"location":"man3/OPENSSL_malloc/","title":"OPENSSL_malloc","text":""},{"location":"man3/OPENSSL_malloc/#name","title":"NAME","text":"

OPENSSL_malloc_init, OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, OPENSSL_strdup, OPENSSL_strndup, OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul, CRYPTO_strdup, CRYPTO_strndup, OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, CRYPTO_clear_realloc, CRYPTO_clear_free, CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn, CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, CRYPTO_get_alloc_counts, CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, OPENSSL_MALLOC_FAILURES, OPENSSL_MALLOC_FD - Memory allocation functions

"},{"location":"man3/OPENSSL_malloc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint OPENSSL_malloc_init(void);\n\nvoid *OPENSSL_malloc(size_t num);\nvoid *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr);\nvoid *OPENSSL_zalloc(size_t num);\nvoid *OPENSSL_realloc(void *addr, size_t num);\nvoid OPENSSL_free(void *addr);\nchar *OPENSSL_strdup(const char *str);\nchar *OPENSSL_strndup(const char *str, size_t s);\nsize_t OPENSSL_strlcat(char *dst, const char *src, size_t size);\nsize_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);\nint OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num);\nvoid *OPENSSL_memdup(void *data, size_t s);\nvoid *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);\nvoid OPENSSL_clear_free(void *str, size_t num);\nvoid OPENSSL_cleanse(void *ptr, size_t len);\n\nvoid *CRYPTO_malloc(size_t num, const char *file, int line);\nvoid *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr, \n                           const char *file, int line);\nvoid *CRYPTO_zalloc(size_t num, const char *file, int line);\nvoid *CRYPTO_realloc(void *p, size_t num, const char *file, int line);\nvoid CRYPTO_free(void *str, const char *, int);\nchar *CRYPTO_strdup(const char *p, const char *file, int line);\nchar *CRYPTO_strndup(const char *p, size_t num, const char *file, int line);\nvoid *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,\n                           const char *file, int line);\nvoid CRYPTO_clear_free(void *str, size_t num, const char *, int);\n\ntypedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);\ntypedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,\n                                   int line);\ntypedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);\nvoid CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,\n                              CRYPTO_realloc_fn *realloc_fn,\n                              CRYPTO_free_fn *free_fn);\nint CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,\n                             CRYPTO_realloc_fn realloc_fn,\n                             CRYPTO_free_fn free_fn);\n\nvoid CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);\n\nenv OPENSSL_MALLOC_FAILURES=... <application>\nenv OPENSSL_MALLOC_FD=... <application>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int CRYPTO_mem_leaks(BIO *b);\nint CRYPTO_mem_leaks_fp(FILE *fp);\nint CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),\n                        void *u);\n\nint CRYPTO_set_mem_debug(int onoff);\nint CRYPTO_mem_ctrl(int mode);\nint OPENSSL_mem_debug_push(const char *info);\nint OPENSSL_mem_debug_pop(void);\nint CRYPTO_mem_debug_push(const char *info, const char *file, int line);\nint CRYPTO_mem_debug_pop(void);\n
"},{"location":"man3/OPENSSL_malloc/#description","title":"DESCRIPTION","text":"

OpenSSL memory allocation is handled by the OPENSSL_xxx API. These are generally macro's that add the standard C __FILE__ and __LINE__ parameters and call a lower-level CRYPTO_xxx API. Some functions do not add those parameters, but exist for consistency.

OPENSSL_malloc_init() does nothing and does not need to be called. It is included for compatibility with older versions of OpenSSL.

OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the C malloc(), realloc(), and free() functions. OPENSSL_zalloc() calls memset() to zero the memory before returning.

OPENSSL_aligned_alloc() operates just as OPENSSL_malloc does, but it allows for the caller to specify an alignment value, for instances in which the default alignment of malloc is insufficient for the callers needs. Note, the alignment value must be a power of 2, and the size specified must be a multiple of the alignment. NOTE: The call to OPENSSL_aligned_alloc() accepts a 3rd argument, freeptr which must point to a void pointer. On some platforms, there is no available library call to obtain memory allocations greater than what malloc provides. In this case, OPENSSL_aligned_alloc implements its own alignment routine, allocating additional memory and offsetting the returned pointer to be on the requested alignment boundary. In order to safely free allocations made by this method, the caller must return the value in the freeptr variable, rather than the returned pointer.

OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when the buffer at addr holds sensitive information. The old buffer is filled with zero's by calling OPENSSL_cleanse() before ultimately calling OPENSSL_free(). If the argument to OPENSSL_free() is NULL, nothing is done.

OPENSSL_cleanse() fills ptr of size len with a string of 0's. Use OPENSSL_cleanse() with care if the memory is a mapping of a file. If the storage controller uses write compression, then it's possible that sensitive tail bytes will survive zeroization because the block of zeros will be compressed. If the storage controller uses wear leveling, then the old sensitive data will not be overwritten; rather, a block of 0's will be written at a new physical location.

OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the equivalent C functions, except that memory is allocated by calling the OPENSSL_malloc() and should be released by calling OPENSSL_free().

OPENSSL_strlcpy(), OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C library functions and are provided for portability.

OPENSSL_strtoul() is a wrapper around the POSIX function strtoul, with the same behaviors listed in the POSIX documentation, with the additional behavior that it validates the input str and num parameters for not being NULL, and confirms that at least a single byte of input has been consumed in the translation, returning an error in the event that no bytes were consumed.

If no allocations have been done, it is possible to \"swap out\" the default implementations for OPENSSL_malloc(), OPENSSL_realloc() and OPENSSL_free() and replace them with alternate versions. CRYPTO_get_mem_functions() function fills in the given arguments with the function pointers for the current implementations. With CRYPTO_set_mem_functions(), you can specify a different set of functions. If any of malloc_fn, realloc_fn, or free_fn are NULL, then the function is not changed. While it's permitted to swap out only a few and not all the functions with CRYPTO_set_mem_functions(), it's recommended to swap them all out at once.

If the library is built with the crypto-mdebug option, then one function, CRYPTO_get_alloc_counts(), and two additional environment variables, OPENSSL_MALLOC_FAILURES and OPENSSL_MALLOC_FD, are available.

The function CRYPTO_get_alloc_counts() fills in the number of times each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been called, into the values pointed to by mcount, rcount, and fcount, respectively. If a pointer is NULL, then the corresponding count is not stored.

The variable OPENSSL_MALLOC_FAILURES controls how often allocations should fail. It is a set of fields separated by semicolons, which each field is a count (defaulting to zero) and an optional atsign and percentage (defaulting to 100). If the count is zero, then it lasts forever. For example, 100;@25 or 100@0;0@25 means the first 100 allocations pass, then all other allocations (until the program exits or crashes) have a 25% chance of failing.

If the variable OPENSSL_MALLOC_FD is parsed as a positive integer, then it is taken as an open file descriptor. This is used in conjunction with OPENSSL_MALLOC_FAILURES described above. For every allocation it will log details about how many allocations there have been so far, what percentage chance there is for this allocation failing, and whether it has actually failed. The following example in classic shell syntax shows how to use this (will not work on all platforms):

OPENSSL_MALLOC_FAILURES='200;@10'\nexport OPENSSL_MALLOC_FAILURES\nOPENSSL_MALLOC_FD=3\nexport OPENSSL_MALLOC_FD\n...app invocation... 3>/tmp/log$$\n
"},{"location":"man3/OPENSSL_malloc/#return-values","title":"RETURN VALUES","text":"

OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() return no value.

OPENSSL_malloc(), OPENSSL_aligned_alloc(), OPENSSL_zalloc(), OPENSSL_realloc(), OPENSSL_clear_realloc(), CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), CRYPTO_clear_realloc(), OPENSSL_strdup(), and OPENSSL_strndup() return a pointer to allocated memory or NULL on error.

CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost always because allocations have already happened).

CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and are no-ops that always return -1. OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop() are deprecated and are no-ops that always return 0.

OPENSSL_strtoul() returns 1 on success and 0 in the event that an error has occurred. Specifically, 0 is returned in the following events:

Note that a success condition does not imply that the expected translation has been performed. For instance calling

OPENSSL_strtoul(\"0x12345\", &endptr, 10, &num);\n

will result in a successful translation with num having the value 0, and *endptr = 'x'. Be sure to validate how much data was consumed when calling this function.

"},{"location":"man3/OPENSSL_malloc/#history","title":"HISTORY","text":"

OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_pop(), CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl() were deprecated in OpenSSL 3.0. The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of clang's memory and leak sanitizer. OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc() were added in OpenSSL 3.4.0

"},{"location":"man3/OPENSSL_malloc/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 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.

"},{"location":"man3/OPENSSL_riscvcap/","title":"OPENSSL_riscvcap","text":""},{"location":"man3/OPENSSL_riscvcap/#name","title":"NAME","text":"

OPENSSL_riscvcap - the RISC-V processor capabilities vector

"},{"location":"man3/OPENSSL_riscvcap/#synopsis","title":"SYNOPSIS","text":"
env OPENSSL_riscvcap=... <application>\n
"},{"location":"man3/OPENSSL_riscvcap/#description","title":"DESCRIPTION","text":"

libcrypto supports RISC-V instruction set extensions. These extensions are denoted by individual extension names in the capabilities vector. For Linux platform, when libcrypto is initialized, the results returned by the RISC-V Hardware Probing syscall (hwprobe) are stored in the vector. Otherwise all capabilities are disabled.

To override the set of instructions available to an application, you can set the OPENSSL_riscvcap environment variable before you start the application.

The environment variable is similar to the RISC-V ISA string defined in the RISC-V Instruction Set Manual. It is case insensitive. Though due to the limit of the environment variable parser inside libcrypto, an extension must be prefixed with an underscore to make it recognizable. This also applies to the Vector extension.

OPENSSL_riscvcap=\"rv64gc_v_zba_zbb_zbs...\"\n

Note that extension implication is currently not implemented. For example, when \"rv64gc_b\" is provided as the environment variable, zba/zbb/zbs would not be implied in the capability vector.

Currently only these extensions are recognized:

"},{"location":"man3/OPENSSL_riscvcap/#return-values","title":"RETURN VALUES","text":"

Not available.

"},{"location":"man3/OPENSSL_riscvcap/#examples","title":"EXAMPLES","text":"

Check currently detected capabilities

$ openssl info -cpusettings\nOPENSSL_riscvcap=ZBA_ZBB_ZBC_ZBS_V\n

Disables all instruction set extensions:

OPENSSL_riscvcap=\"rv64gc\"\n

Only enable the vector extension:

OPENSSL_riscvcap=\"rv64gc_v\"\n
"},{"location":"man3/OPENSSL_riscvcap/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OPENSSL_s390xcap/","title":"OPENSSL_s390xcap","text":""},{"location":"man3/OPENSSL_s390xcap/#name","title":"NAME","text":"

OPENSSL_s390xcap - the IBM z processor capabilities vector

"},{"location":"man3/OPENSSL_s390xcap/#synopsis","title":"SYNOPSIS","text":"
env OPENSSL_s390xcap=... <application>\n
"},{"location":"man3/OPENSSL_s390xcap/#description","title":"DESCRIPTION","text":"

libcrypto supports z/Architecture instruction set extensions. These extensions are denoted by individual bits in the capabilities vector. When libcrypto is initialized, the bits returned by the STFLE instruction and by the QUERY functions are stored in the vector.

To change the set of instructions available to an application, you can set the OPENSSL_s390xcap environment variable before you start the application. After initialization, the capability vector is ANDed bitwise with a mask which is derived from the environment variable.

The environment variable is a semicolon-separated list of tokens which is processed from left to right (whitespace is ignored):

OPENSSL_s390xcap=\"<tok1>;<tok2>;...\"\n

There are four types of tokens:

The 64-bit masks are specified in hexadecimal notation. The 0x prefix is optional. Prefix a mask with a tilde, ~, to denote a bitwise NOT operation.

The following is a list of significant bits for each instruction. Colon rows separate the individual 64-bit masks. The bit numbers in the first column are consistent with [1], that is, 0 denotes the leftmost bit and the numbering is continuous across 64-bit mask boundaries.

     Bit     Mask     Facility/Function\n\nstfle:\n  #   # 17    1<<46    message-security assist\n  #   # 25    1<<38    store-clock-fast facility\n     :\n  #   # 76    1<<51    message-security assist extension 3\n  #   # 77    1<<50    message-security assist extension 4\n  #   # 86    1<<41    message-security-assist extension 12\n     :\n     #129    1<<62    vector facility\n     #134    1<<57    vector packed decimal facility\n     #135    1<<56    vector enhancements facility 1\n     #146    1<<45    message-security assist extension 8\n     #155    1<<36    message-security assist extension 9\n\nkimd :\n  #   #  1    1<<62    KIMD-SHA-1\n  #   #  2    1<<61    KIMD-SHA-256\n  #   #  3    1<<60    KIMD-SHA-512\n  #   # 32    1<<31    KIMD-SHA3-224\n  #   # 33    1<<30    KIMD-SHA3-256\n  #   # 34    1<<29    KIMD-SHA3-384\n  #   # 35    1<<28    KIMD-SHA3-512\n  #   # 36    1<<27    KIMD-SHAKE-128\n  #   # 37    1<<26    KIMD-SHAKE-256\n     :\n  #   # 65    1<<62    KIMD-GHASH\n\nklmd :\n  #   # 32    1<<31    KLMD-SHA3-224\n  #   # 33    1<<30    KLMD-SHA3-256\n  #   # 34    1<<29    KLMD-SHA3-384\n  #   # 35    1<<28    KLMD-SHA3-512\n  #   # 36    1<<27    KLMD-SHAKE-128\n  #   # 37    1<<26    KLMD-SHAKE-256\n     :\n\nkm   :\n  #   # 18    1<<45    KM-AES-128\n  #   # 19    1<<44    KM-AES-192\n  #   # 20    1<<43    KM-AES-256\n  #   # 50    1<<13    KM-XTS-AES-128\n  #   # 52    1<<11    KM-XTS-AES-256\n     :\n  #   # 82    1<<45    KM-XTS-AES-128-MSA10\n  #   # 84    1<<43    KM-XTS-AES-256-MSA10\n\nkmc  :\n  #   # 18    1<<45    KMC-AES-128\n  #   # 19    1<<44    KMC-AES-192\n  #   # 20    1<<43    KMC-AES-256\n     :\n\nkmac :\n  #   # 18    1<<45    KMAC-AES-128\n  #   # 19    1<<44    KMAC-AES-192\n  #   # 20    1<<43    KMAC-AES-256\n     :\n  #   # 112   1<<15    KMAC-SHA-224\n  #   # 113   1<<14    KMAC-SHA-256\n  #   # 114   1<<13    KMAC-SHA-384\n  #   # 115   1<<12    KMAC-SHA-512\n\nkmctr:\n     :\n\nkmo  :\n  #   # 18    1<<45    KMO-AES-128\n  #   # 19    1<<44    KMO-AES-192\n  #   # 20    1<<43    KMO-AES-256\n     :\n\nkmf  :\n  #   # 18    1<<45    KMF-AES-128\n  #   # 19    1<<44    KMF-AES-192\n  #   # 20    1<<43    KMF-AES-256\n     :\n\nprno :\n     :\n\nkma  :\n  #   # 18    1<<45    KMA-GCM-AES-128\n  #   # 19    1<<44    KMA-GCM-AES-192\n  #   # 20    1<<43    KMA-GCM-AES-256\n     :\n\npcc  :\n     :\n  #   # 64    1<<63    PCC-Scalar-Multiply-P256\n  #   # 65    1<<62    PCC-Scalar-Multiply-P384\n  #   # 66    1<<61    PCC-Scalar-Multiply-P521\n  #   # 72    1<<55    PCC-Scalar-Multiply-Ed25519\n  #   # 73    1<<54    PCC-Scalar-Multiply-Ed448\n  #   # 80    1<<47    PCC-Scalar-Multiply-X25519\n  #   # 81    1<<46    PCC-Scalar-Multiply-X448\n\nkdsa :\n  #   #  1    1<<62    KDSA-ECDSA-Verify-P256\n  #   #  2    1<<61    KDSA-ECDSA-Verify-P384\n  #   #  3    1<<60    KDSA-ECDSA-Verify-P521\n  #   #  9    1<<54    KDSA-ECDSA-Sign-P256\n  #   # 10    1<<53    KDSA-ECDSA-Sign-P384\n  #   # 11    1<<52    KDSA-ECDSA-Sign-P521\n  #   # 32    1<<31    KDSA-EdDSA-Verify-Ed25519\n  #   # 36    1<<27    KDSA-EdDSA-Verify-Ed448\n  #   # 40    1<<23    KDSA-EdDSA-Sign-Ed25519\n  #   # 44    1<<19    KDSA-EdDSA-Sign-Ed448\n     :\n
"},{"location":"man3/OPENSSL_s390xcap/#return-values","title":"RETURN VALUES","text":"

Not available.

"},{"location":"man3/OPENSSL_s390xcap/#examples","title":"EXAMPLES","text":"

Disables all instruction set extensions which the z196 processor does not implement:

OPENSSL_s390xcap=\"z196\"\n

Disables the vector facility:

OPENSSL_s390xcap=\"stfle:~0:~0:~0x4000000000000000\"\n

Disables the KM-XTS-AES and the KIMD-SHAKE function codes:

OPENSSL_s390xcap=\"km:~0x2800:~0;kimd:~0xc000000:~0\"\n
"},{"location":"man3/OPENSSL_s390xcap/#see-also","title":"SEE ALSO","text":"

[1] z/Architecture Principles of Operation, SA22-7832-12

"},{"location":"man3/OPENSSL_s390xcap/#copyright","title":"COPYRIGHT","text":"

Copyright 2018-2024 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.

"},{"location":"man3/OPENSSL_secure_malloc/","title":"OPENSSL_secure_malloc","text":""},{"location":"man3/OPENSSL_secure_malloc/#name","title":"NAME","text":"

CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc, OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free, CRYPTO_secure_free, OPENSSL_secure_clear_free, CRYPTO_secure_clear_free, OPENSSL_secure_actual_size, CRYPTO_secure_allocated, CRYPTO_secure_used - secure heap storage

"},{"location":"man3/OPENSSL_secure_malloc/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint CRYPTO_secure_malloc_init(size_t size, size_t minsize);\n\nint CRYPTO_secure_malloc_initialized();\n\nint CRYPTO_secure_malloc_done();\n\nvoid *OPENSSL_secure_malloc(size_t num);\nvoid *CRYPTO_secure_malloc(size_t num, const char *file, int line);\n\nvoid *OPENSSL_secure_zalloc(size_t num);\nvoid *CRYPTO_secure_zalloc(size_t num, const char *file, int line);\n\nvoid OPENSSL_secure_free(void* ptr);\nvoid CRYPTO_secure_free(void *ptr, const char *, int);\n\nvoid OPENSSL_secure_clear_free(void* ptr, size_t num);\nvoid CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int);\n\nsize_t OPENSSL_secure_actual_size(const void *ptr);\n\nint CRYPTO_secure_allocated(const void *ptr);\nsize_t CRYPTO_secure_used();\n
"},{"location":"man3/OPENSSL_secure_malloc/#description","title":"DESCRIPTION","text":"

In order to help protect applications (particularly long-running servers) from pointer overruns or underruns that could return arbitrary data from the program's dynamic memory area, where keys and other sensitive information might be stored, OpenSSL supports the concept of a \"secure heap.\" The level and type of security guarantees depend on the operating system. It is a good idea to review the code and see if it addresses your threat model and concerns.

If a secure heap is used, then private key BIGNUM values are stored there. This protects long-term storage of private keys, but will not necessarily put all intermediate values and computations there.

CRYPTO_secure_malloc_init() creates the secure heap, with the specified size in bytes. The minsize parameter is the minimum size to allocate from the heap or zero to use a reasonable default value. Both size and, if specified, minsize must be a power of two and minsize should generally be small, for example 16 or 32. minsize must be less than a quarter of size in any case.

CRYPTO_secure_malloc_initialized() indicates whether or not the secure heap as been initialized and is available.

CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable to the process if all secure memory has been freed. It can take noticeably long to complete.

OPENSSL_secure_malloc() allocates num bytes from the heap. If CRYPTO_secure_malloc_init() is not called, this is equivalent to calling OPENSSL_malloc(). It is a macro that expands to CRYPTO_secure_malloc() and adds the __FILE__ and __LINE__ parameters.

OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively, except that they call memset() to zero the memory before returning.

OPENSSL_secure_free() releases the memory at ptr back to the heap. It must be called with a value previously obtained from OPENSSL_secure_malloc(). If CRYPTO_secure_malloc_init() is not called, this is equivalent to calling OPENSSL_free(). It exists for consistency with OPENSSL_secure_malloc() , and is a macro that expands to CRYPTO_secure_free() and adds the __FILE__ and __LINE__ parameters.. If the argument to OPENSSL_secure_free() is NULL, nothing is done.

OPENSSL_secure_clear_free() is similar to OPENSSL_secure_free() except that it has an additional num parameter which is used to clear the memory if it was not allocated from the secure heap. If CRYPTO_secure_malloc_init() is not called, this is equivalent to calling OPENSSL_clear_free(). If the argument to OPENSSL_secure_clear_free() is NULL, nothing is done.

OPENSSL_secure_actual_size() tells the actual size allocated to the pointer; implementations may allocate more space than initially requested, in order to \"round up\" and reduce secure heap fragmentation.

OPENSSL_secure_allocated() tells if a pointer is allocated in the secure heap.

CRYPTO_secure_used() returns the number of bytes allocated in the secure heap.

"},{"location":"man3/OPENSSL_secure_malloc/#return-values","title":"RETURN VALUES","text":"

CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful, and 2 if successful but the heap could not be protected by memory mapping.

CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is available (that is, if CRYPTO_secure_malloc_init() has been called, but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not.

OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into the secure heap of the requested size, or NULL if memory could not be allocated.

CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not.

CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not.

OPENSSL_secure_free() and OPENSSL_secure_clear_free() return no values.

"},{"location":"man3/OPENSSL_secure_malloc/#see-also","title":"SEE ALSO","text":"

OPENSSL_malloc(3), BN_new(3)

"},{"location":"man3/OPENSSL_secure_malloc/#history","title":"HISTORY","text":"

The OPENSSL_secure_clear_free() function was added in OpenSSL 1.1.0g.

The second argument to CRYPTO_secure_malloc_init() was changed from an int to a size_t in OpenSSL 3.0.

"},{"location":"man3/OPENSSL_secure_malloc/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2024 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.

"},{"location":"man3/OPENSSL_strcasecmp/","title":"OPENSSL_strcasecmp","text":""},{"location":"man3/OPENSSL_strcasecmp/#name","title":"NAME","text":"

OPENSSL_strcasecmp, OPENSSL_strncasecmp - compare two strings ignoring case

"},{"location":"man3/OPENSSL_strcasecmp/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint OPENSSL_strcasecmp(const char *s1, const char *s2);\nint OPENSSL_strncasecmp(const char *s1, const char *s2, size_t n);\n
"},{"location":"man3/OPENSSL_strcasecmp/#description","title":"DESCRIPTION","text":"

The OPENSSL_strcasecmp function performs a byte-by-byte comparison of the strings s1 and s2, ignoring the case of the characters.

The OPENSSL_strncasecmp function is similar, except that it compares no more than n bytes of s1 and s2.

In POSIX-compatible system and on Windows these functions use \"C\" locale for case insensitive. Otherwise the comparison is done in current locale.

"},{"location":"man3/OPENSSL_strcasecmp/#return-values","title":"RETURN VALUES","text":"

Both functions return an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

"},{"location":"man3/OPENSSL_strcasecmp/#notes","title":"NOTES","text":"

OpenSSL extensively uses case insensitive comparison of ASCII strings. Though OpenSSL itself is locale-agnostic, the applications using OpenSSL libraries may unpredictably suffer when they use localization (e.g. Turkish locale is well-known with a specific I/i cases). These functions use C locale for string comparison.

"},{"location":"man3/OPENSSL_strcasecmp/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OSSL_ALGORITHM/","title":"OSSL_ALGORITHM","text":""},{"location":"man3/OSSL_ALGORITHM/#name","title":"NAME","text":"

OSSL_ALGORITHM - OpenSSL Core type to define a fetchable algorithm

"},{"location":"man3/OSSL_ALGORITHM/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/core.h>\n\ntypedef struct ossl_algorithm_st OSSL_ALGORITHM;\nstruct ossl_algorithm_st {\n    const char *algorithm_names;     /* key */\n    const char *property_definition; /* key */\n    const OSSL_DISPATCH *implementation;\n    const char *algorithm_description;\n};\n
"},{"location":"man3/OSSL_ALGORITHM/#description","title":"DESCRIPTION","text":"

The OSSL_ALGORITHM type is a public structure that describes an algorithm that a provider(7) provides. Arrays of this type are returned by providers on demand from the OpenSSL libraries to describe what algorithms the providers provide implementations of, and with what properties.

Arrays of this type must be terminated with a tuple where algorithm_names is NULL.

This type of array is typically returned by the provider's operation querying function, further described in \"Provider Functions\" in provider-base(7).

"},{"location":"man3/OSSL_ALGORITHM/#ossl_algorithm-fields","title":"OSSL_ALGORITHM fields","text":""},{"location":"man3/OSSL_ALGORITHM/#notes","title":"NOTES","text":""},{"location":"man3/OSSL_ALGORITHM/#on-the-subject-of-algorithm-names","title":"On the subject of algorithm names","text":"

Providers may find the need to register ASN.1 OIDs for algorithms using OBJ_create(3) (via the core_obj_create upcall described in provider-base(7), because some application or library -- possibly still the OpenSSL libraries, even -- use NIDs to look up algorithms.

In that scenario, you must make sure that the corresponding OSSL_ALGORITHM's algorithm_names includes both the short and the long name.

Most of the time, registering ASN.1 OIDs like this shouldn't be necessary, and applications and libraries are encouraged to use OBJ_obj2txt(3) to get a text representation of the OID, which may be a long or short name for OIDs that are registered, or the OID itself in canonical decimal text form if not (or if OBJ_obj2txt(3) is called with no_name = 1).

It's recommended to make sure that the corresponding OSSL_ALGORITHM's algorithm_names include known names as well as the OID itself in canonical decimal text form. That should cover all scenarios.

"},{"location":"man3/OSSL_ALGORITHM/#see-also","title":"SEE ALSO","text":"

crypto(7), provider-base(7), openssl-core.h(7), openssl-core_dispatch.h(7), OSSL_DISPATCH(3)

"},{"location":"man3/OSSL_ALGORITHM/#history","title":"HISTORY","text":"

OSSL_ALGORITHM was added in OpenSSL 3.0

"},{"location":"man3/OSSL_ALGORITHM/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OSSL_CALLBACK/","title":"OSSL_CALLBACK","text":""},{"location":"man3/OSSL_CALLBACK/#name","title":"NAME","text":"

OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK - OpenSSL Core type to define callbacks

"},{"location":"man3/OSSL_CALLBACK/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/core.h>\ntypedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);\ntypedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,\n                                       size_t *pass_len,\n                                       const OSSL_PARAM params[],\n                                       void *arg);\n
"},{"location":"man3/OSSL_CALLBACK/#description","title":"DESCRIPTION","text":"

For certain events or activities, provider functionality may need help from the application or the calling OpenSSL libraries themselves. For example, user input or direct (possibly optional) user output could be implemented this way.

Callback functions themselves are always provided by or through the calling OpenSSL libraries, along with a generic pointer to data arg. As far as the function receiving the pointer to the function pointer and arg is concerned, the data that arg points at is opaque, and the pointer should simply be passed back to the callback function when it's called.

"},{"location":"man3/OSSL_CALLBACK/#see-also","title":"SEE ALSO","text":"

openssl-core.h(7)

"},{"location":"man3/OSSL_CALLBACK/#history","title":"HISTORY","text":"

The types described here were added in OpenSSL 3.0.

"},{"location":"man3/OSSL_CALLBACK/#copyright","title":"COPYRIGHT","text":"

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

"},{"location":"man3/OSSL_CMP_ATAV_set0/","title":"OSSL_CMP_ATAV_set0","text":""},{"location":"man3/OSSL_CMP_ATAV_set0/#name","title":"NAME","text":"

OSSL_CMP_ATAV, OSSL_CMP_ATAV_create, OSSL_CMP_ATAV_set0, OSSL_CMP_ATAV_get0_type, OSSL_CMP_ATAV_get0_value, OSSL_CMP_ATAV_new_algId, OSSL_CMP_ATAV_get0_algId, OSSL_CMP_ATAV_new_rsaKeyLen, OSSL_CMP_ATAV_get_rsaKeyLen, OSSL_CMP_ATAVS, OSSL_CMP_ATAV_push1, OSSL_CMP_ATAV_free - OSSL_CMP_ATAV utility functions

"},{"location":"man3/OSSL_CMP_ATAV_set0/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cmp.h>\n\ntypedef OSSL_CRMF_ATTRIBUTETYPEANDVALUE OSSL_CMP_ATAV;\nOSSL_CMP_ATAV *OSSL_CMP_ATAV_create(ASN1_OBJECT *type, ASN1_TYPE *value);\nvoid OSSL_CMP_ATAV_set0(OSSL_CMP_ATAV *atav, ASN1_OBJECT *type,\n                        ASN1_TYPE *value);\nASN1_OBJECT *OSSL_CMP_ATAV_get0_type(const OSSL_CMP_ATAV *atav);\nASN1_TYPE *OSSL_CMP_ATAV_get0_value(const OSSL_CMP_ATAV *atav);\n\nOSSL_CMP_ATAV *OSSL_CMP_ATAV_new_algId(const X509_ALGOR *alg);\nX509_ALGOR *OSSL_CMP_ATAV_get0_algId(const OSSL_CMP_ATAV *atav);\nOSSL_CMP_ATAV *OSSL_CMP_ATAV_new_rsaKeyLen(int len);\nint OSSL_CMP_ATAV_get_rsaKeyLen(const OSSL_CMP_ATAV *atav);\n\ntypedef STACK_OF(OSSL_CRMF_ATTRIBUTETYPEANDVALUE) OSSL_CMP_ATAVS;\nint OSSL_CMP_ATAV_push1(OSSL_CMP_ATAVS **sk_p, const OSSL_CMP_ATAV *atav);\nvoid OSSL_CMP_ATAV_free(OSSL_CMP_ATAV *atav);\n
"},{"location":"man3/OSSL_CMP_ATAV_set0/#description","title":"DESCRIPTION","text":"

OSSL_CMP_ATAV is a short hand of OSSL_CRMF_ATTRIBUTETYPEANDVALUE, defined in RFC 4211 Appendix B. It is typically used in CertRequest structures, but also in CertReqTemplateContent structures for key specifications.

OSSL_CMP_ATAV_create() creates a new OSSL_CMP_ATAV structure and fills it in. It combines OSSL_CMP_ATAV_new() and OSSL_CMP_ATAV_set0().

OSSL_CMP_ATAV_set0() sets the atav with an infoType of type and an infoValue of value. The pointers type and value may be NULL, otherwise they must not be freed up after the call because their ownership is transferred to atav. The itav pointer must not be NULL.

OSSL_CMP_ATAV_get0_type() returns a direct pointer to the infoType in the atav unless it is NULL.

OSSL_CMP_ATAV_get0_value() returns a direct pointer to the infoValue in the atav as generic ASN1_TYPE pointer unless atav is NULL.

OSSL_CMP_ATAV_new_algId() creates a new OSSL_CMP_ATAV structure of type algId and fills it in with a copy of the given alg.

OSSL_CMP_ATAV_get0_algId() returns a direct pointer to the algId infoValue in the atav of type X509_ALGOR or NULL if atav is NULL or does not contain an algId.

OSSL_CMP_ATAV_new_rsaKeyLen() creates a new OSSL_CMP_ATAV structure of type rsaKeyLen and fills it in with the given len, which must be positive.

OSSL_CMP_ATAV_get_rsaKeyLen() returns the RSA key length in rsaKeyLen infoValue in the atav, -1 if atav is NULL or does not contain an rsaKeyLen or cannot be parsed, or -2 if the value is less than 1 or is greater than INT_MAX.

OSSL_CMP_ATAV_push1() pushes a copy of atav to the stack of OSSL_CMP_ATAV pointed to by *sk_p. It creates a new stack if *sk_p points to NULL.

OSSL_CMP_ATAV_free() deallocates atav. It is defined as a macro.

"},{"location":"man3/OSSL_CMP_ATAV_set0/#notes","title":"NOTES","text":"

CMP is defined in RFC 4210. CRMF is defined in RFC 4211.

"},{"location":"man3/OSSL_CMP_ATAV_set0/#return-values","title":"RETURN VALUES","text":"

OSSL_CMP_ATAV_create(), OSSL_CMP_ATAV_new_algId(), and OSSL_CMP_ATAV_new_rsaKeyLen() return a pointer to the ATAV structure on success, or NULL on error.

OSSL_CMP_ATAV_set0() and OSSL_CMP_ATAV_free() do not return a value.

OSSL_CMP_ATAV_get0_type(), OSSL_CMP_ATAV_get0_value(), and OSSL_CMP_ATAV_get0_algId() return the respective pointer or NULL if their input is NULL.

OSSL_CMP_ATAV_get_rsaKeyLen() return a key length in bits or < 0 on error.

OSSL_CMP_ATAV_push1() returns 1 on success, 0 on error.

"},{"location":"man3/OSSL_CMP_ATAV_set0/#see-also","title":"SEE ALSO","text":"

OSSL_CMP_ITAV_new0_certReqTemplate(3), ASN1_TYPE_set(3)

"},{"location":"man3/OSSL_CMP_ATAV_set0/#history","title":"HISTORY","text":"

The OSSL_CMP_ATAV type and related functions were added in OpenSSL 3.4.

"},{"location":"man3/OSSL_CMP_ATAV_set0/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2024 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.

"},{"location":"man3/OSSL_CMP_CTX_new/","title":"OSSL_CMP_CTX_new","text":""},{"location":"man3/OSSL_CMP_CTX_new/#name","title":"NAME","text":"

OSSL_CMP_CTX_new, OSSL_CMP_CTX_free, OSSL_CMP_CTX_reinit, OSSL_CMP_CTX_get0_libctx, OSSL_CMP_CTX_get0_propq, OSSL_CMP_CTX_set_option, OSSL_CMP_CTX_get_option, OSSL_CMP_CTX_set_log_cb, OSSL_CMP_CTX_set_log_verbosity, OSSL_CMP_CTX_print_errors, OSSL_CMP_CTX_set1_serverPath, OSSL_CMP_CTX_set1_server, OSSL_CMP_CTX_set_serverPort, OSSL_CMP_CTX_set1_proxy, OSSL_CMP_CTX_set1_no_proxy, OSSL_CMP_CTX_set_http_cb, OSSL_CMP_CTX_set_http_cb_arg, OSSL_CMP_CTX_get_http_cb_arg, OSSL_CMP_transfer_cb_t, OSSL_CMP_CTX_set_transfer_cb, OSSL_CMP_CTX_set_transfer_cb_arg, OSSL_CMP_CTX_get_transfer_cb_arg, OSSL_CMP_CTX_set1_srvCert, OSSL_CMP_CTX_set1_expected_sender, OSSL_CMP_CTX_set0_trusted, OSSL_CMP_CTX_set0_trustedStore, OSSL_CMP_CTX_get0_trusted, OSSL_CMP_CTX_get0_trustedStore, OSSL_CMP_CTX_set1_untrusted, OSSL_CMP_CTX_get0_untrusted, OSSL_CMP_CTX_set1_cert, OSSL_CMP_CTX_build_cert_chain, OSSL_CMP_CTX_set1_pkey, OSSL_CMP_CTX_set1_referenceValue, OSSL_CMP_CTX_set1_secretValue, OSSL_CMP_CTX_set1_recipient, OSSL_CMP_CTX_push0_geninfo_ITAV, OSSL_CMP_CTX_reset_geninfo_ITAVs, OSSL_CMP_CTX_get0_geninfo_ITAVs, OSSL_CMP_CTX_set1_extraCertsOut, OSSL_CMP_CTX_set0_newPkey, OSSL_CMP_CTX_get0_newPkey, OSSL_CMP_CTX_set1_issuer, OSSL_CMP_CTX_set1_serialNumber, OSSL_CMP_CTX_set1_subjectName, OSSL_CMP_CTX_push1_subjectAltName, OSSL_CMP_CTX_set0_reqExtensions, OSSL_CMP_CTX_reqExtensions_have_SAN, OSSL_CMP_CTX_push0_policy, OSSL_CMP_CTX_set1_oldCert, OSSL_CMP_CTX_set1_p10CSR, OSSL_CMP_CTX_push0_genm_ITAV, OSSL_CMP_certConf_cb_t, OSSL_CMP_certConf_cb, OSSL_CMP_CTX_set_certConf_cb, OSSL_CMP_CTX_set_certConf_cb_arg, OSSL_CMP_CTX_get_certConf_cb_arg, OSSL_CMP_CTX_get_status, OSSL_CMP_CTX_get0_statusString, OSSL_CMP_CTX_get_failInfoCode, OSSL_CMP_CTX_get0_validatedSrvCert, OSSL_CMP_CTX_get0_newCert, OSSL_CMP_CTX_get1_newChain, OSSL_CMP_CTX_get1_caPubs, OSSL_CMP_CTX_get1_extraCertsIn, OSSL_CMP_CTX_set1_transactionID, OSSL_CMP_CTX_set1_senderNonce - functions for managing the CMP client context data structure

"},{"location":"man3/OSSL_CMP_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cmp.h>\n\nOSSL_CMP_CTX *OSSL_CMP_CTX_new(OSSL_LIB_CTX *libctx, const char *propq);\nvoid OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx);\nOSSL_LIB_CTX *OSSL_CMP_CTX_get0_libctx(const OSSL_CMP_CTX *ctx);\nconst char *OSSL_CMP_CTX_get0_propq(const OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val);\nint OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt);\n\n/* logging and error reporting: */\nint OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb);\n#define OSSL_CMP_CTX_set_log_verbosity(ctx, level)\nvoid OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx);\n\n/* message transfer: */\nint OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);\nint OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address);\nint OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);\nint OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name);\nint OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names);\nint OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb);\nint OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg);\nvoid *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx);\ntypedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx,\n                                                const OSSL_CMP_MSG *req);\nint OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx,\n                                 OSSL_CMP_transfer_cb_t cb);\nint OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg);\nvoid *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx);\n\n/* server authentication: */\nint OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert);\nint OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx,\n                                     const X509_NAME *name);\n#define OSSL_CMP_CTX_set0_trusted OSSL_CMP_CTX_set0_trustedStore\nint OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store);\n#define OSSL_CMP_CTX_get0_trusted OSSL_CMP_CTX_get0_trustedStore\nX509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_set1_untrusted(OSSL_CMP_CTX *ctx, STACK_OF(X509) *certs);\nSTACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted(const OSSL_CMP_CTX *ctx);\n\n/* client authentication: */\nint OSSL_CMP_CTX_set1_cert(OSSL_CMP_CTX *ctx, X509 *cert);\nint OSSL_CMP_CTX_build_cert_chain(OSSL_CMP_CTX *ctx, X509_STORE *own_trusted,\n                                  STACK_OF(X509) *candidates);\nint OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey);\nint OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx,\n                                     const unsigned char *ref, int len);\nint OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx,\n                                  const unsigned char *sec, int len);\n\n/* CMP message header and extra certificates: */\nint OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name);\nint OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);\nint OSSL_CMP_CTX_reset_geninfo_ITAVs(OSSL_CMP_CTX *ctx);\nSTACK_OF(OSSL_CMP_ITAV)\n    *OSSL_CMP_CTX_get0_geninfo_ITAVs(const OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx,\n                                    STACK_OF(X509) *extraCertsOut);\n\n/* certificate template: */\nint OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey);\nEVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv);\nint OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name);\nint OSSL_CMP_CTX_set1_serialNumber(OSSL_CMP_CTX *ctx, const ASN1_INTEGER *sn);\nint OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name);\nint OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx,\n                                      const GENERAL_NAME *name);\nint OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts);\nint OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo);\nint OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert);\nint OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr);\n\n/* misc body contents: */\nint OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);\n\n/* certificate confirmation: */\ntypedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert,\n                                      int fail_info, const char **txt);\nint OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info,\n                         const char **text);\nint OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb);\nint OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg);\nvoid *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx);\n\n/* result fetching: */\nint OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx);\nOSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx);\nint OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx);\n\nX509 *OSSL_CMP_CTX_get0_validatedSrvCert(const OSSL_CMP_CTX *ctx);\nX509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx);\nSTACK_OF(X509) *OSSL_CMP_CTX_get1_newChain(const OSSL_CMP_CTX *ctx);\nSTACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx);\nSTACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx);\n\n/* for testing and debugging purposes: */\nint OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx,\n                                    const ASN1_OCTET_STRING *id);\nint OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx,\n                                  const ASN1_OCTET_STRING *nonce);\n
"},{"location":"man3/OSSL_CMP_CTX_new/#description","title":"DESCRIPTION","text":"

This is the context API for using CMP (Certificate Management Protocol) with OpenSSL.

OSSL_CMP_CTX_new() allocates an OSSL_CMP_CTX structure associated with the library context libctx and property query string propq, both of which may be NULL to select the defaults. It initializes the remaining fields to their default values - for instance, the logging verbosity is set to OSSL_CMP_LOG_INFO, the message timeout is set to 120 seconds, and the proof-of-possession method is set to OSSL_CRMF_POPO_SIGNATURE.

OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure. If the argument is NULL, nothing is done.

OSSL_CMP_CTX_reinit() prepares the given ctx for a further transaction by clearing the internal CMP transaction (aka session) status, PKIStatusInfo, and any previous results (newCert, newChain, caPubs, and extraCertsIn) from the last executed transaction. It also clears any ITAVs that were added by OSSL_CMP_CTX_push0_genm_ITAV(). All other field values (i.e., CMP options) are retained for potential reuse.

OSSL_CMP_CTX_get0_libctx() returns the libctx argument that was used when constructing ctx with OSSL_CMP_CTX_new(), which may be NULL.

OSSL_CMP_CTX_get0_propq() returns the propq argument that was used when constructing ctx with OSSL_CMP_CTX_new(), which may be NULL.

OSSL_CMP_CTX_set_option() sets the given value for the given option (e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure.

The following options can be set: