diff options
Diffstat (limited to 'crypto/openssl/doc')
41 files changed, 756 insertions, 409 deletions
diff --git a/crypto/openssl/doc/man1/ca.pod b/crypto/openssl/doc/man1/ca.pod index 9b282e6479a8..e998eabf8358 100644 --- a/crypto/openssl/doc/man1/ca.pod +++ b/crypto/openssl/doc/man1/ca.pod @@ -250,8 +250,10 @@ for all available algorithms. =item B<-subj arg> Supersedes subject name given in the request. -The arg must be formatted as I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted, but the corresponding type will not be included +in the resulting certificate. =item B<-utf8> diff --git a/crypto/openssl/doc/man1/enc.pod b/crypto/openssl/doc/man1/enc.pod index 01cca4ea93f1..2136a9497849 100644 --- a/crypto/openssl/doc/man1/enc.pod +++ b/crypto/openssl/doc/man1/enc.pod @@ -257,7 +257,7 @@ ones provided by configured engines. The B<enc> program does not support authenticated encryption modes like CCM and GCM, and will not support such modes in the future. The B<enc> interface by necessity must begin streaming output (e.g., -to standard output when B<-out> is not used before the authentication +to standard output when B<-out> is not used) before the authentication tag could be validated, leading to the usage of B<enc> in pipelines that begin processing untrusted data and are not capable of rolling back upon authentication failure. The AEAD modes currently in common @@ -277,6 +277,7 @@ standard data format and performs the needed key/iv/nonce management. bf-cbc Blowfish in CBC mode bf Alias for bf-cbc + blowfish Alias for bf-cbc bf-cfb Blowfish in CFB mode bf-ecb Blowfish in ECB mode bf-ofb Blowfish in OFB mode @@ -288,6 +289,8 @@ standard data format and performs the needed key/iv/nonce management. cast5-ecb CAST5 in ECB mode cast5-ofb CAST5 in OFB mode + chacha20 ChaCha20 algorithm + des-cbc DES in CBC mode des Alias for des-cbc des-cfb DES in CFB mode @@ -334,6 +337,19 @@ standard data format and performs the needed key/iv/nonce management. rc5-ecb RC5 cipher in ECB mode rc5-ofb RC5 cipher in OFB mode + seed-cbc SEED cipher in CBC mode + seed Alias for seed-cbc + seed-cfb SEED cipher in CFB mode + seed-ecb SEED cipher in ECB mode + seed-ofb SEED cipher in OFB mode + + sm4-cbc SM4 cipher in CBC mode + sm4 Alias for sm4-cbc + sm4-cfb SM4 cipher in CFB mode + sm4-ctr SM4 cipher in CTR mode + sm4-ecb SM4 cipher in ECB mode + sm4-ofb SM4 cipher in OFB mode + aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode aes[128|192|256] Alias for aes-[128|192|256]-cbc aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode @@ -343,6 +359,15 @@ standard data format and performs the needed key/iv/nonce management. aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode + aria-[128|192|256]-cbc 128/192/256 bit ARIA in CBC mode + aria[128|192|256] Alias for aria-[128|192|256]-cbc + aria-[128|192|256]-cfb 128/192/256 bit ARIA in 128 bit CFB mode + aria-[128|192|256]-cfb1 128/192/256 bit ARIA in 1 bit CFB mode + aria-[128|192|256]-cfb8 128/192/256 bit ARIA in 8 bit CFB mode + aria-[128|192|256]-ctr 128/192/256 bit ARIA in CTR mode + aria-[128|192|256]-ecb 128/192/256 bit ARIA in ECB mode + aria-[128|192|256]-ofb 128/192/256 bit ARIA in OFB mode + camellia-[128|192|256]-cbc 128/192/256 bit Camellia in CBC mode camellia[128|192|256] Alias for camellia-[128|192|256]-cbc camellia-[128|192|256]-cfb 128/192/256 bit Camellia in 128 bit CFB mode @@ -362,26 +387,25 @@ Decode the same file openssl base64 -d -in file.b64 -out file.bin -Encrypt a file using triple DES in CBC mode using a prompted password: +Encrypt a file using AES-128 using a prompted password +and PBKDF2 key derivation: - openssl des3 -salt -in file.txt -out file.des3 + openssl enc -aes128 -pbkdf2 -in file.txt -out file.aes128 Decrypt a file using a supplied password: - openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword + openssl enc -aes128 -pbkdf2 -d -in file.aes128 -out file.txt \ + -pass pass:<password> Encrypt a file then base64 encode it (so it can be sent via mail for example) -using Blowfish in CBC mode: - - openssl bf -a -salt -in file.txt -out file.bf - -Base64 decode a file then decrypt it: +using AES-256 in CTR mode and PBKDF2 key derivation: - openssl bf -d -salt -a -in file.bf -out file.txt + openssl enc -aes-256-ctr -pbkdf2 -a -in file.txt -out file.aes256 -Decrypt some data using a supplied 40 bit RC4 key: +Base64 decode a file then decrypt it using a password supplied in a file: - openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 + openssl enc -aes-256-ctr -pbkdf2 -d -a -in file.aes256 -out file.txt \ + -pass file:<passfile> =head1 BUGS diff --git a/crypto/openssl/doc/man1/openssl.pod b/crypto/openssl/doc/man1/openssl.pod index c656a34ec032..a39cf963d988 100644 --- a/crypto/openssl/doc/man1/openssl.pod +++ b/crypto/openssl/doc/man1/openssl.pod @@ -40,6 +40,9 @@ The B<openssl> program provides a rich variety of commands (I<command> in the SYNOPSIS above), each of which often has a wealth of options and arguments (I<command_opts> and I<command_args> in the SYNOPSIS). +Detailed documentation and use cases for most standard subcommands are available +(e.g., L<x509(1)> or L<openssl-x509(1)>). + Many commands use an external configuration file for some or all of their arguments and have a B<-config> option to specify that file. The environment variable B<OPENSSL_CONF> can be used to specify @@ -369,8 +372,38 @@ SM3 Digest =head2 Encoding and Cipher Commands +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 L<enc(1)> for more information and command usage. + =over 4 +=item B<aes128>, B<aes-128-cbc>, B<aes-128-cfb>, B<aes-128-ctr>, B<aes-128-ecb>, B<aes-128-ofb> + +AES-128 Cipher + +=item B<aes192>, B<aes-192-cbc>, B<aes-192-cfb>, B<aes-192-ctr>, B<aes-192-ecb>, B<aes-192-ofb> + +AES-192 Cipher + +=item B<aes256>, B<aes-256-cbc>, B<aes-256-cfb>, B<aes-256-ctr>, B<aes-256-ecb>, B<aes-256-ofb> + +AES-256 Cipher + +=item B<aria128>, B<aria-128-cbc>, B<aria-128-cfb>, B<aria-128-ctr>, B<aria-128-ecb>, B<aria-128-ofb> + +Aria-128 Cipher + +=item B<aria192>, B<aria-192-cbc>, B<aria-192-cfb>, B<aria-192-ctr>, B<aria-192-ecb>, B<aria-192-ofb> + +Aria-192 Cipher + +=item B<aria256>, B<aria-256-cbc>, B<aria-256-cfb>, B<aria-256-ctr>, B<aria-256-ecb>, B<aria-256-ofb> + +Aria-256 Cipher + =item B<base64> Base64 Encoding @@ -379,6 +412,18 @@ Base64 Encoding Blowfish Cipher +=item B<camellia128>, B<camellia-128-cbc>, B<camellia-128-cfb>, B<camellia-128-ctr>, B<camellia-128-ecb>, B<camellia-128-ofb> + +Camellia-128 Cipher + +=item B<camellia192>, B<camellia-192-cbc>, B<camellia-192-cfb>, B<camellia-192-ctr>, B<camellia-192-ecb>, B<camellia-192-ofb> + +Camellia-192 Cipher + +=item B<camellia256>, B<camellia-256-cbc>, B<camellia-256-cfb>, B<camellia-256-ctr>, B<camellia-256-ecb>, B<camellia-256-ofb> + +Camellia-256 Cipher + =item B<cast>, B<cast-cbc> CAST Cipher @@ -387,6 +432,10 @@ CAST Cipher CAST5 Cipher +=item B<chacha20> + +Chacha20 Cipher + =item B<des>, B<des-cbc>, B<des-cfb>, B<des-ecb>, B<des-ede>, B<des-ede-cbc>, B<des-ede-cfb>, B<des-ede-ofb>, B<des-ofb> DES Cipher @@ -411,6 +460,14 @@ RC4 Cipher RC5 Cipher +=item B<seed>, B<seed-cbc>, B<seed-cfb>, B<seed-ecb>, B<seed-ofb> + +SEED Cipher + +=item B<sm4>, B<sm4-cbc>, B<sm4-cfb>, B<sm4-ctr>, B<sm4-ecb>, B<sm4-ofb> + +SM4 Cipher + =back =head1 OPTIONS diff --git a/crypto/openssl/doc/man1/req.pod b/crypto/openssl/doc/man1/req.pod index 113cd9b6c985..c76d63d6fd81 100644 --- a/crypto/openssl/doc/man1/req.pod +++ b/crypto/openssl/doc/man1/req.pod @@ -221,8 +221,10 @@ see L<openssl(1)/COMMAND SUMMARY>. Sets subject name for new request or supersedes the subject name when processing a request. -The arg must be formatted as I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted, but the corresponding type will not be included +in the request. =item B<-multivalue-rdn> diff --git a/crypto/openssl/doc/man1/rsa.pod b/crypto/openssl/doc/man1/rsa.pod index 14a8fb1e2989..37f64616c00f 100644 --- a/crypto/openssl/doc/man1/rsa.pod +++ b/crypto/openssl/doc/man1/rsa.pod @@ -9,8 +9,8 @@ rsa - RSA key processing tool B<openssl> B<rsa> [B<-help>] -[B<-inform PEM|NET|DER>] -[B<-outform PEM|NET|DER>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] [B<-in filename>] [B<-passin arg>] [B<-out filename>] @@ -53,16 +53,15 @@ utility. Print out a usage message. -=item B<-inform DER|NET|PEM> +=item B<-inform DER|PEM> This specifies the input format. The B<DER> option uses an ASN1 DER encoded form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. The B<PEM> form is the default format: it consists of the B<DER> format base64 encoded with additional header and footer lines. On input PKCS#8 format private -keys are also accepted. The B<NET> form is a format is described in the B<NOTES> -section. +keys are also accepted. -=item B<-outform DER|NET|PEM> +=item B<-outform DER|PEM> This specifies the output format, the options have the same meaning and default as the B<-inform> option. @@ -158,17 +157,6 @@ The PEM B<RSAPublicKey> format uses the header and footer lines: -----BEGIN RSA PUBLIC KEY----- -----END RSA PUBLIC KEY----- -The B<NET> form is a format compatible with older Netscape servers -and Microsoft IIS .key files, this uses unsalted RC4 for its encryption. -It is not very secure and so should only be used when necessary. - -Some newer version of IIS have additional data in the exported .key -files. To use these with the utility, view the file with a binary editor -and look for the string "private-key", then trace back to the byte -sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data -from this point onwards to another file and use that as the input -to the B<rsa> utility with the B<-inform NET> option. - =head1 EXAMPLES To remove the pass phrase on an RSA private key: @@ -197,9 +185,6 @@ Output the public part of a private key in B<RSAPublicKey> format: =head1 BUGS -The command line password arguments don't currently work with -B<NET> format. - There should be an option that automatically handles .key files, without having to manually edit them. diff --git a/crypto/openssl/doc/man1/s_server.pod b/crypto/openssl/doc/man1/s_server.pod index 07016fc46131..f4c4eda35313 100644 --- a/crypto/openssl/doc/man1/s_server.pod +++ b/crypto/openssl/doc/man1/s_server.pod @@ -405,13 +405,14 @@ Inhibit printing of session and certificate information. Sends a status message back to the client when it connects. This includes information about the ciphers used and various session parameters. The output is in HTML format so this option will normally be used with a -web browser. +web browser. Cannot be used in conjunction with B<-early_data>. =item B<-WWW> Emulates a simple web server. Pages will be resolved relative to the current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. +requested the file ./page.html will be loaded. Cannot be used in conjunction +with B<-early_data>. =item B<-tlsextdebug> @@ -423,7 +424,8 @@ Emulates a simple web server. Pages will be resolved relative to the current directory, for example if the URL https://myhost/page.html is requested the file ./page.html will be loaded. The files loaded are assumed to contain a complete and correct HTTP response (lines that -are part of the HTTP response line and headers must end with CRLF). +are part of the HTTP response line and headers must end with CRLF). Cannot be +used in conjunction with B<-early_data>. =item B<-id_prefix val> @@ -488,7 +490,8 @@ output. =item B<-rev> Simple test server which just reverses the text received from the client -and sends it back to the server. Also sets B<-brief>. +and sends it back to the server. Also sets B<-brief>. Cannot be used in +conjunction with B<-early_data>. =item B<-async> @@ -711,7 +714,8 @@ greater than or equal to 0. =item B<-early_data> -Accept early data where possible. +Accept early data where possible. Cannot be used in conjunction with B<-www>, +B<-WWW>, B<-HTTP> or B<-rev>. =item B<-anti_replay>, B<-no_anti_replay> diff --git a/crypto/openssl/doc/man1/storeutl.pod b/crypto/openssl/doc/man1/storeutl.pod index 3f26ab500b83..083f0282469e 100644 --- a/crypto/openssl/doc/man1/storeutl.pod +++ b/crypto/openssl/doc/man1/storeutl.pod @@ -82,8 +82,11 @@ returned. =item B<-subject arg> Search for an object having the subject name B<arg>. -The arg must be formatted as I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted but are ignored for the search. That is, +a search with an empty value will have the same effect as not specifying +the type at all. =item B<-issuer arg> diff --git a/crypto/openssl/doc/man1/x509.pod b/crypto/openssl/doc/man1/x509.pod index 6e4d28815530..547da5da2368 100644 --- a/crypto/openssl/doc/man1/x509.pod +++ b/crypto/openssl/doc/man1/x509.pod @@ -9,8 +9,8 @@ x509 - Certificate display and signing utility B<openssl> B<x509> [B<-help>] -[B<-inform DER|PEM|NET>] -[B<-outform DER|PEM|NET>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] [B<-keyform DER|PEM>] [B<-CAform DER|PEM>] [B<-CAkeyform DER|PEM>] @@ -86,16 +86,15 @@ various sections. Print out a usage message. -=item B<-inform DER|PEM|NET> +=item B<-inform DER|PEM> This specifies the input format normally the command will expect an X509 certificate but this can change if other options such as B<-req> are present. The DER format is the DER encoding of the certificate and PEM is the base64 encoding of the DER encoding with header and footer lines -added. The NET option is an obscure Netscape server format that is now -obsolete. The default format is PEM. +added. The default format is PEM. -=item B<-outform DER|PEM|NET> +=item B<-outform DER|PEM> This specifies the output format, the options have the same meaning and default as the B<-inform> option. diff --git a/crypto/openssl/doc/man3/DES_random_key.pod b/crypto/openssl/doc/man3/DES_random_key.pod index f543bea1ee7b..6e0394d637b2 100644 --- a/crypto/openssl/doc/man3/DES_random_key.pod +++ b/crypto/openssl/doc/man3/DES_random_key.pod @@ -99,7 +99,7 @@ algorithm. There are two phases to the use of DES encryption. The first is the generation of a I<DES_key_schedule> from a key, the second is the -actual encryption. A DES key is of type I<DES_cblock>. This type is +actual encryption. A DES key is of type I<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. @@ -170,42 +170,42 @@ 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 -an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. +C<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 I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>. This form of Triple-DES is used by the RSAREF library. -DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block +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() encrypt/decrypts using cipher feedback mode. This -method takes an array of characters as input and outputs and array of +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 I<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 I<numbits>, this function is only -suggested for use when sending small numbers of characters. +suggested for use when sending a small number of characters. DES_cfb64_encrypt() -implements CFB mode of DES with 64bit feedback. Why is this +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, no 8 byte padding. Each call to this +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 :-). +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 and array of +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 I<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 small numbers of characters. +a complete DES ECB encryption per I<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. @@ -232,10 +232,10 @@ 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 +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. +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 diff --git a/crypto/openssl/doc/man3/EVP_DigestInit.pod b/crypto/openssl/doc/man3/EVP_DigestInit.pod index 0fedd17ce6c6..5ecbcc5e8992 100644 --- a/crypto/openssl/doc/man3/EVP_DigestInit.pod +++ b/crypto/openssl/doc/man3/EVP_DigestInit.pod @@ -310,16 +310,17 @@ This example digests the data "Test Message\n" and "Hello World\n", using the digest name passed on the command line. #include <stdio.h> + #include <string.h> #include <openssl/evp.h> - main(int argc, char *argv[]) + int main(int argc, char *argv[]) { EVP_MD_CTX *mdctx; const EVP_MD *md; char mess1[] = "Test Message\n"; char mess2[] = "Hello World\n"; unsigned char md_value[EVP_MAX_MD_SIZE]; - int md_len, i; + unsigned int md_len, i; if (argv[1] == NULL) { printf("Usage: mdtest digestname\n"); diff --git a/crypto/openssl/doc/man3/EVP_PKEY_CTX_ctrl.pod b/crypto/openssl/doc/man3/EVP_PKEY_CTX_ctrl.pod index e1a107c06e3c..4982e9205305 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/crypto/openssl/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -4,20 +4,55 @@ 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_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_set_rsa_keygen_primes, +EVP_PKEY_CTX_set_rsa_mgf1_md, +EVP_PKEY_CTX_get_rsa_mgf1_md, +EVP_PKEY_CTX_set_rsa_oaep_md, +EVP_PKEY_CTX_get_rsa_oaep_md, +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_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_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 - algorithm specific control operations @@ -27,9 +62,13 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2); + int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, + int cmd, uint64_t value); int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, const char *value); + int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md); + int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); @@ -38,22 +77,58 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len #include <openssl/rsa.h> int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); + int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad); int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *len); int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); + int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes); + int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); + int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); + int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len); + int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label); #include <openssl/dsa.h> + int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); #include <openssl/dh.h> + int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len); int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); + int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type); int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); + int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); + int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); + int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); + int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx); + int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid); + int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid); + int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); + int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); + int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); + int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); #include <openssl/ec.h> + int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); + int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode); + int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx); + int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); + int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx); + int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); + int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); + int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); + int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); @@ -73,6 +148,9 @@ and B<p2> is 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 macros below. +The function EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a +uint64 value as B<p2> to EVP_PKEY_CTX_ctrl(). + The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm specific control operation to a context B<ctx> in string form. This is intended to be used for options specified on the command line or in text @@ -80,6 +158,9 @@ files. The commands supported are documented in the openssl utility command line pages for the option B<-pkeyopt> which is supported by the B<pkeyutl>, B<genpkey> and B<req> commands. +The function EVP_PKEY_CTX_md() sends a message digest control operation +to the context B<ctx>. The message digest is specified by its name B<md>. + All the remaining "functions" are implemented as macros. The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used @@ -99,12 +180,14 @@ L<EVP_PKEY_new_raw_private_key(3)> or similar functions instead of this macro. The EVP_PKEY_CTX_set_mac_key() macro can be used with any of the algorithms supported by the L<EVP_PKEY_new_raw_private_key(3)> function. -The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. -The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, -RSA_SSLV23_PADDING for SSLv23 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) and -RSA_PKCS1_PSS_PADDING (sign and verify only). +=head2 RSA parameters + +The EVP_PKEY_CTX_set_rsa_padding() macro sets the RSA padding mode for B<ctx>. +The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1 +padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for +no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and +decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations +only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only). Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() is used. If this macro is called for PKCS#1 padding the plaintext buffer is @@ -116,41 +199,154 @@ 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. +The EVP_PKEY_CTX_get_rsa_padding() macro gets the RSA padding mode for B<ctx>. + The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to -B<len> as its name implies it is only supported for PSS padding. Three special -values are supported: RSA_PSS_SALTLEN_DIGEST sets the salt length to the -digest length, RSA_PSS_SALTLEN_MAX sets the salt length to the maximum -permissible value. When verifying RSA_PSS_SALTLEN_AUTO causes the salt length +B<len>. As its name implies it is only supported for PSS padding. Three special +values are supported: B<RSA_PSS_SALTLEN_DIGEST> sets the salt length to the +digest length, B<RSA_PSS_SALTLEN_MAX> sets the salt length to the maximum +permissible value. When verifying B<RSA_PSS_SALTLEN_AUTO> causes the salt length to be automatically determined based on the B<PSS> block structure. If this macro is not called maximum salt length is used when signing and auto detection when verifying is used by default. +The EVP_PKEY_CTX_get_rsa_pss_saltlen() macro gets the RSA PSS salt length +for B<ctx>. The padding mode must have been set to B<RSA_PKCS1_PSS_PADDING>. + The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for RSA key generation to B<bits>. If not specified 1024 bits is used. The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value -for RSA key generation to B<pubexp> currently it should be an odd integer. The +for RSA key generation to B<pubexp>. Currently it should be an odd integer. The B<pubexp> pointer is used internally by this function so it should not be -modified or free after the call. If this macro is not called then 65537 is used. +modified or freed after the call. If not specified 65537 is used. + +The EVP_PKEY_CTX_set_rsa_keygen_primes() macro sets the number of primes for +RSA key generation to B<primes>. If not specified 2 is used. + +The EVP_PKEY_CTX_set_rsa_mgf1_md() macro sets the MGF1 digest for RSA padding +schemes to B<md>. If not explicitly set the signing digest is used. The +padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> +or B<RSA_PKCS1_PSS_PADDING>. + +The EVP_PKEY_CTX_get_rsa_mgf1_md() macro gets the MGF1 digest for B<ctx>. +If not explicitly set the signing digest is used. The padding mode must have +been set to B<RSA_PKCS1_OAEP_PADDING> or B<RSA_PKCS1_PSS_PADDING>. + +The EVP_PKEY_CTX_set_rsa_oaep_md() macro sets the message digest type used +in RSA OAEP to B<md>. The padding mode must have been set to +B<RSA_PKCS1_OAEP_PADDING>. + +The EVP_PKEY_CTX_get_rsa_oaep_md() macro gets the message digest type used +in RSA OAEP to B<md>. The padding mode must have been set to +B<RSA_PKCS1_OAEP_PADDING>. + +The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to +B<label> and its length to B<len>. If B<label> is NULL or B<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 B<label>. +The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>. + +The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to +B<label>. The return value is the label length. The padding mode +must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned +by the library and should not be freed by the caller. + +=head2 DSA parameters -The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used +The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used for DSA parameter generation to B<bits>. If not specified 1024 is used. -The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH +=head2 DH parameters + +The EVP_PKEY_CTX_set_dh_paramgen_prime_len() macro sets the length of the DH prime parameter B<p> for DH parameter generation. If this macro is not called -then 1024 is used. +then 1024 is used. Only accepts lengths greater than or equal to 256. + +The EVP_PKEY_CTX_set_dh_paramgen_subprime_len() macro sets the length of the DH +optional subprime parameter B<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 x9.42. The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> for DH parameter generation. If not specified 2 is used. +The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH +parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH. +The default is 0. + The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH prime B<p>. If B<pad> is zero (the default) then no padding is performed. EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to -B<nid>. The B<nid> parameter must be B<NID_ffdhe2048>, B<NID_ffdhe3072>, -B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>. This macro can be -called during parameter or key generation. +B<nid> as defined in RFC7919. The B<nid> parameter must be B<NID_ffdhe2048>, +B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, B<NID_ffdhe8192> +or B<NID_undef> to clear the stored value. This macro can be called during +parameter or key generation. +The nid parameter and the rfc5114 parameter are mutually exclusive. + +The EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() macros are +synonymous. They set the DH parameters to the values defined in RFC5114. The +B<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 B<ctx> must have a key type of +B<EVP_PKEY_DHX>. +The rfc5114 parameter and the nid parameter are mutually exclusive. + +=head2 DH key derivation function parameters + +Note that all of the following functions require that the B<ctx> parameter has +a private key type of B<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). + +The EVP_PKEY_CTX_set_dh_kdf_type() macro sets the key derivation function type +to B<kdf> for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> +and B<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 B<kdf_oid>, B<kdf_md> and B<kdf_outlen> parameters must also be specified. + +The EVP_PKEY_CTX_get_dh_kdf_type() macro gets the key derivation function type +for B<ctx> used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> +and B<EVP_PKEY_DH_KDF_X9_42>. + +The EVP_PKEY_CTX_set0_dh_kdf_oid() macro sets the key derivation function +object identifier to B<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 B<oid>. + +The EVP_PKEY_CTX_get0_dh_kdf_oid() macro gets the key derivation function oid +for B<ctx> used for DH key derivation. The resulting pointer is owned by the +library and should not be freed by the caller. + +The EVP_PKEY_CTX_set_dh_kdf_md() macro sets the key derivation function +message digest to B<md> for DH key derivation. Note that RFC2631 specifies +that this digest should be SHA1 but OpenSSL tolerates other digests. + +The EVP_PKEY_CTX_get_dh_kdf_md() macro gets the key derivation function +message digest for B<ctx> used for DH key derivation. + +The EVP_PKEY_CTX_set_dh_kdf_outlen() macro sets the key derivation function +output length to B<len> for DH key derivation. + +The EVP_PKEY_CTX_get_dh_kdf_outlen() macro gets the key derivation function +output length for B<ctx> used for DH key derivation. + +The EVP_PKEY_CTX_set0_dh_kdf_ukm() macro sets the user key material to +B<ukm> and its length to B<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 B<ukm>. + +The EVP_PKEY_CTX_get0_dh_kdf_ukm() macro gets the user key material for B<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. + +=head2 EC parameters The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter generation to B<nid>. For EC parameter generation this macro must be called @@ -158,7 +354,7 @@ or an error occurs because there is no default curve. This function can also be called to set the curve explicitly when generating an EC key. -The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to +The EVP_PKEY_CTX_set_ec_param_enc() macro sets the EC parameter encoding to B<param_enc> when generating EC parameters or an EC key. The encoding can be B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. @@ -166,6 +362,53 @@ For maximum compatibility the named curve form should be used. Note: the B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous versions should use 0 instead. +=head2 ECDH parameters + +The EVP_PKEY_CTX_set_ecdh_cofactor_mode() macro sets the cofactor mode to +B<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. + +The EVP_PKEY_CTX_get_ecdh_cofactor_mode() macro returns the cofactor mode for +B<ctx> used for ECDH key derivation. Possible values are 1 when cofactor key +derivation is enabled and 0 otherwise. + +=head2 ECDH key derivation function parameters + +The EVP_PKEY_CTX_set_ecdh_kdf_type() macro sets the key derivation function type +to B<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE> +and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63. +When using key derivation, the B<kdf_md> and B<kdf_outlen> parameters must +also be specified. + +The EVP_PKEY_CTX_get_ecdh_kdf_type() macro returns the key derivation function +type for B<ctx> used for ECDH key derivation. Possible values are +B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>. + +The EVP_PKEY_CTX_set_ecdh_kdf_md() macro sets the key derivation function +message digest to B<md> for ECDH key derivation. Note that X9.63 specifies +that this digest should be SHA1 but OpenSSL tolerates other digests. + +The EVP_PKEY_CTX_get_ecdh_kdf_md() macro gets the key derivation function +message digest for B<ctx> used for ECDH key derivation. + +The EVP_PKEY_CTX_set_ecdh_kdf_outlen() macro sets the key derivation function +output length to B<len> for ECDH key derivation. + +The EVP_PKEY_CTX_get_ecdh_kdf_outlen() macro gets the key derivation function +output length for B<ctx> used for ECDH key derivation. + +The EVP_PKEY_CTX_set0_ecdh_kdf_ukm() macro sets the user key material to B<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 B<ukm>. + +The EVP_PKEY_CTX_get0_ecdh_kdf_ukm() macro gets the user key material for B<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. + +=head2 Other parameters + The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() macros 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 B<id> with @@ -191,7 +434,7 @@ L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>, L<EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)> +L<EVP_PKEY_derive(3)>, L<EVP_PKEY_keygen(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod b/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod index 1433a50a6ffe..e8f19cfc9980 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod +++ b/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod @@ -68,12 +68,12 @@ error occurs. =back -EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF. +EVP_PKEY_CTX_set_hkdf_md() sets the message digest associated with the HKDF. EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the buffer B<salt>. Any existing value is replaced. -EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer +EVP_PKEY_CTX_set1_hkdf_key() sets the key to B<keylen> bytes of the buffer B<key>. Any existing value is replaced. EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the diff --git a/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod b/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod index bd1193e24a5b..7578278a6cfc 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod +++ b/crypto/openssl/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod @@ -32,7 +32,7 @@ The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length. If the key has usage restrictions then an error is returned if an attempt is made to set the salt length below the minimum value. It is otherwise similar to the B<RSA> operation except detection of the salt length (using -RSA_PSS_SALTLEN_AUTO is not supported for verification if the key has +RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has usage restrictions. The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros @@ -43,7 +43,7 @@ similar to the B<RSA> versions. =head2 Key Generation -As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() +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. diff --git a/crypto/openssl/doc/man3/EVP_PKEY_set1_RSA.pod b/crypto/openssl/doc/man3/EVP_PKEY_set1_RSA.pod index 749c52c375af..d10fc59d8bcc 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_set1_RSA.pod +++ b/crypto/openssl/doc/man3/EVP_PKEY_set1_RSA.pod @@ -6,8 +6,10 @@ 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_get0_hmac, EVP_PKEY_type, EVP_PKEY_id, -EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assignment functions +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_type, EVP_PKEY_id, EVP_PKEY_base_id, EVP_PKEY_set_alias_type, +EVP_PKEY_set1_engine - EVP_PKEY assignment functions =head1 SYNOPSIS @@ -24,6 +26,8 @@ EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assig EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); + const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len); + const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len); RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey); DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey); DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey); @@ -33,6 +37,8 @@ EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assig int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); + int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); + int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); int EVP_PKEY_id(const EVP_PKEY *pkey); int EVP_PKEY_base_id(const EVP_PKEY *pkey); @@ -50,14 +56,15 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or B<NULL> if the key is not of the correct type. -EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), -EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the -referenced key in B<pkey> or B<NULL> if the key is not of the -correct type but the reference count of the returned key is -B<not> incremented and so must not be freed up after use. +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() also return the referenced key in B<pkey> or B<NULL> +if the key is not of the correct type but the reference count of the +returned key is B<not> incremented and so must not be freed up after use. -EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> +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() also set the referenced key to B<key> however these use the supplied B<key> internally and so B<key> will be freed when the parent B<pkey> is freed. @@ -89,8 +96,9 @@ In accordance with the OpenSSL naming convention the key obtained from or assigned to the B<pkey> using the B<1> functions must be freed as well as B<pkey>. -EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -and EVP_PKEY_assign_EC_KEY() are implemented as macros. +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. Most applications wishing to know a key type will simply call EVP_PKEY_base_id() and will not care about the actual type: @@ -119,8 +127,9 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if an error occurred. -EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. +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_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. diff --git a/crypto/openssl/doc/man3/EVP_aes.pod b/crypto/openssl/doc/man3/EVP_aes.pod index 6a893993c6a8..4192a9ec369f 100644 --- a/crypto/openssl/doc/man3/EVP_aes.pod +++ b/crypto/openssl/doc/man3/EVP_aes.pod @@ -14,6 +14,9 @@ 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, @@ -75,6 +78,9 @@ 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(), @@ -170,7 +176,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_aria.pod b/crypto/openssl/doc/man3/EVP_aria.pod index 3b6ad3576ed1..fbb79187546c 100644 --- a/crypto/openssl/doc/man3/EVP_aria.pod +++ b/crypto/openssl/doc/man3/EVP_aria.pod @@ -14,6 +14,9 @@ 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, @@ -60,6 +63,9 @@ 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(), @@ -100,7 +106,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_bf_cbc.pod b/crypto/openssl/doc/man3/EVP_bf_cbc.pod index 4a9d3a9f5e76..505d41b4943f 100644 --- a/crypto/openssl/doc/man3/EVP_bf_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_bf_cbc.pod @@ -4,6 +4,7 @@ EVP_bf_cbc, EVP_bf_cfb, +EVP_bf_cfb64, EVP_bf_ecb, EVP_bf_ofb - EVP Blowfish cipher @@ -14,6 +15,7 @@ EVP_bf_ofb const EVP_CIPHER *EVP_bf_cbc(void) const EVP_CIPHER *EVP_bf_cfb(void) + const EVP_CIPHER *EVP_bf_cfb64(void) const EVP_CIPHER *EVP_bf_ecb(void) const EVP_CIPHER *EVP_bf_ofb(void) @@ -27,6 +29,7 @@ This is a variable key length cipher. =item EVP_bf_cbc(), EVP_bf_cfb(), +EVP_bf_cfb64(), EVP_bf_ecb(), EVP_bf_ofb() @@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_camellia.pod b/crypto/openssl/doc/man3/EVP_camellia.pod index 75602cf64573..6ad59f84b110 100644 --- a/crypto/openssl/doc/man3/EVP_camellia.pod +++ b/crypto/openssl/doc/man3/EVP_camellia.pod @@ -14,6 +14,9 @@ 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, @@ -54,6 +57,9 @@ 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(), @@ -83,7 +89,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_cast5_cbc.pod b/crypto/openssl/doc/man3/EVP_cast5_cbc.pod index 01c38414698b..0be07279259f 100644 --- a/crypto/openssl/doc/man3/EVP_cast5_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_cast5_cbc.pod @@ -4,6 +4,7 @@ EVP_cast5_cbc, EVP_cast5_cfb, +EVP_cast5_cfb64, EVP_cast5_ecb, EVP_cast5_ofb - EVP CAST cipher @@ -14,6 +15,7 @@ EVP_cast5_ofb const EVP_CIPHER *EVP_cast5_cbc(void) const EVP_CIPHER *EVP_cast5_cfb(void) + const EVP_CIPHER *EVP_cast5_cfb64(void) const EVP_CIPHER *EVP_cast5_ecb(void) const EVP_CIPHER *EVP_cast5_ofb(void) @@ -28,6 +30,7 @@ This is a variable key length cipher. =item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), +EVP_cast5_cfb64(), EVP_cast5_ofb() CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. @@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_des.pod b/crypto/openssl/doc/man3/EVP_des.pod index 836c399c849e..a05149ff8586 100644 --- a/crypto/openssl/doc/man3/EVP_des.pod +++ b/crypto/openssl/doc/man3/EVP_des.pod @@ -6,19 +6,24 @@ 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_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_ede_cbc +EVP_des_ede3_wrap - EVP DES cipher =head1 SYNOPSIS @@ -43,27 +48,32 @@ EVP_des_ecb(), EVP_des_cfb(), EVP_des_cfb1(), EVP_des_cfb8(), +EVP_des_cfb64(), EVP_des_ofb() -DES in CBC, ECB, CFB with 128-bit shift, CFB with 1-bit shift, CFB with 8-bit -shift and OFB modes respectively. +DES in CBC, ECB, CFB with 64-bit shift, CFB with 1-bit shift, CFB with 8-bit +shift and OFB modes. =item EVP_des_ede(), EVP_des_ede_cbc(), -EVP_des_ede_ofb(), -EVP_des_ede_cfb() +EVP_des_ede_cfb(), +EVP_des_ede_cfb64(), +EVP_des_ede_ecb(), +EVP_des_ede_ofb() -Two key triple DES in ECB, CBC, CFB and OFB modes respectively. +Two key triple DES in ECB, CBC, CFB with 64-bit shift and OFB modes. =item 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() -Three-key triple DES in ECB, CBC, CFB with 128-bit shift, CFB with 1-bit shift, -CFB with 8-bit shift and OFB modes respectively. +Three-key triple DES in ECB, CBC, CFB with 64-bit shift, CFB with 1-bit shift, +CFB with 8-bit shift and OFB modes. =item EVP_des_ede3_wrap() @@ -85,7 +95,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_idea_cbc.pod b/crypto/openssl/doc/man3/EVP_idea_cbc.pod index ace79885e9a3..14dcc903b525 100644 --- a/crypto/openssl/doc/man3/EVP_idea_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_idea_cbc.pod @@ -4,6 +4,7 @@ EVP_idea_cbc, EVP_idea_cfb, +EVP_idea_cfb64, EVP_idea_ecb, EVP_idea_ofb - EVP IDEA cipher @@ -14,6 +15,7 @@ EVP_idea_ofb const EVP_CIPHER *EVP_idea_cbc(void) const EVP_CIPHER *EVP_idea_cfb(void) + const EVP_CIPHER *EVP_idea_cfb64(void) const EVP_CIPHER *EVP_idea_ecb(void) const EVP_CIPHER *EVP_idea_ofb(void) @@ -25,6 +27,7 @@ The IDEA encryption algorithm for EVP. =item EVP_idea_cbc(), EVP_idea_cfb(), +EVP_idea_cfb64(), EVP_idea_ecb(), EVP_idea_ofb() @@ -46,7 +49,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_md5.pod b/crypto/openssl/doc/man3/EVP_md5.pod index 8101143b54ec..725fcbf5e227 100644 --- a/crypto/openssl/doc/man3/EVP_md5.pod +++ b/crypto/openssl/doc/man3/EVP_md5.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_md5 +EVP_md5, +EVP_md5_sha1 - MD5 For EVP =head1 SYNOPSIS @@ -10,6 +11,7 @@ EVP_md5 #include <openssl/evp.h> const EVP_MD *EVP_md5(void); + const EVP_MD *EVP_md5_sha1(void); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/man3/EVP_rc2_cbc.pod b/crypto/openssl/doc/man3/EVP_rc2_cbc.pod index 0958e930537e..79769b82635a 100644 --- a/crypto/openssl/doc/man3/EVP_rc2_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_rc2_cbc.pod @@ -4,6 +4,7 @@ EVP_rc2_cbc, EVP_rc2_cfb, +EVP_rc2_cfb64, EVP_rc2_ecb, EVP_rc2_ofb, EVP_rc2_40_cbc, @@ -16,6 +17,7 @@ EVP_rc2_64_cbc const EVP_CIPHER *EVP_rc2_cbc(void) const EVP_CIPHER *EVP_rc2_cfb(void) + const EVP_CIPHER *EVP_rc2_cfb64(void) const EVP_CIPHER *EVP_rc2_ecb(void) const EVP_CIPHER *EVP_rc2_ofb(void) const EVP_CIPHER *EVP_rc2_40_cbc(void) @@ -29,6 +31,7 @@ The RC2 encryption algorithm for EVP. =item EVP_rc2_cbc(), EVP_rc2_cfb(), +EVP_rc2_cfb64(), EVP_rc2_ecb(), EVP_rc2_ofb() @@ -62,7 +65,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_rc5_32_12_16_cbc.pod b/crypto/openssl/doc/man3/EVP_rc5_32_12_16_cbc.pod index 56175e99c44b..442a114ea9ce 100644 --- a/crypto/openssl/doc/man3/EVP_rc5_32_12_16_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_rc5_32_12_16_cbc.pod @@ -4,6 +4,7 @@ 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 @@ -14,6 +15,7 @@ EVP_rc5_32_12_16_ofb const EVP_CIPHER *EVP_rc5_32_12_16_cbc(void) const EVP_CIPHER *EVP_rc5_32_12_16_cfb(void) + const EVP_CIPHER *EVP_rc5_32_12_16_cfb64(void) const EVP_CIPHER *EVP_rc5_32_12_16_ecb(void) const EVP_CIPHER *EVP_rc5_32_12_16_ofb(void) @@ -25,6 +27,7 @@ The RC5 encryption algorithm for EVP. =item 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() @@ -53,7 +56,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_seed_cbc.pod b/crypto/openssl/doc/man3/EVP_seed_cbc.pod index e9f1f695a915..0d2329510d5e 100644 --- a/crypto/openssl/doc/man3/EVP_seed_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_seed_cbc.pod @@ -4,6 +4,7 @@ EVP_seed_cbc, EVP_seed_cfb, +EVP_seed_cfb128, EVP_seed_ecb, EVP_seed_ofb - EVP SEED cipher @@ -14,6 +15,7 @@ EVP_seed_ofb const EVP_CIPHER *EVP_seed_cbc(void) const EVP_CIPHER *EVP_seed_cfb(void) + const EVP_CIPHER *EVP_seed_cfb128(void) const EVP_CIPHER *EVP_seed_ecb(void) const EVP_CIPHER *EVP_seed_ofb(void) @@ -27,6 +29,7 @@ All modes below use a key length of 128 bits and acts on blocks of 128-bits. =item EVP_seed_cbc(), EVP_seed_cfb(), +EVP_seed_cfb128(), EVP_seed_ecb(), EVP_seed_ofb() @@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/EVP_sm4_cbc.pod b/crypto/openssl/doc/man3/EVP_sm4_cbc.pod index 4e0240919836..ecd51f09d41f 100644 --- a/crypto/openssl/doc/man3/EVP_sm4_cbc.pod +++ b/crypto/openssl/doc/man3/EVP_sm4_cbc.pod @@ -5,6 +5,7 @@ EVP_sm4_cbc, EVP_sm4_ecb, EVP_sm4_cfb, +EVP_sm4_cfb128, EVP_sm4_ofb, EVP_sm4_ctr - EVP SM4 cipher @@ -16,6 +17,7 @@ EVP_sm4_ctr const EVP_CIPHER *EVP_sm4_cbc(void); const EVP_CIPHER *EVP_sm4_ecb(void); const EVP_CIPHER *EVP_sm4_cfb(void); + const EVP_CIPHER *EVP_sm4_cfb128(void); const EVP_CIPHER *EVP_sm4_ofb(void); const EVP_CIPHER *EVP_sm4_ctr(void); @@ -30,6 +32,7 @@ All modes below use a key length of 128 bits and acts on blocks of 128 bits. =item EVP_sm4_cbc(), EVP_sm4_ecb(), EVP_sm4_cfb(), +EVP_sm4_cfb128(), EVP_sm4_ofb(), EVP_sm4_ctr() diff --git a/crypto/openssl/doc/man3/OPENSSL_VERSION_NUMBER.pod b/crypto/openssl/doc/man3/OPENSSL_VERSION_NUMBER.pod index 6eca1134b161..55a55c706a51 100644 --- a/crypto/openssl/doc/man3/OPENSSL_VERSION_NUMBER.pod +++ b/crypto/openssl/doc/man3/OPENSSL_VERSION_NUMBER.pod @@ -2,13 +2,14 @@ =head1 NAME -OPENSSL_VERSION_NUMBER, OpenSSL_version, +OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_TEXT, OpenSSL_version, OpenSSL_version_num - get OpenSSL version number =head1 SYNOPSIS #include <openssl/opensslv.h> #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL + #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx" #include <openssl/crypto.h> @@ -45,6 +46,10 @@ Version 0.9.5a had an interim interpretation that is like the current one, except the patch level got the highest bit set, to keep continuity. The number was therefore 0x0090581f. +OPENSSL_VERSION_TEXT is the text variant of the version number and the +release date. For example, +"OpenSSL 1.0.1a 15 Oct 2015". + OpenSSL_version_num() returns the version number. OpenSSL_version() returns different strings depending on B<t>: diff --git a/crypto/openssl/doc/man3/RSA_meth_new.pod b/crypto/openssl/doc/man3/RSA_meth_new.pod index 69ba9dfc5ac3..f21095156c0f 100644 --- a/crypto/openssl/doc/man3/RSA_meth_new.pod +++ b/crypto/openssl/doc/man3/RSA_meth_new.pod @@ -64,10 +64,10 @@ RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen unsigned char *to, RSA *rsa, int padding)); /* Can be null */ - int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *I, + int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx); int RSA_meth_set_mod_exp(RSA_METHOD *rsa, - int (*mod_exp)(BIGNUM *r0, const BIGNUM *I, RSA *rsa, + int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx)); /* Can be null */ diff --git a/crypto/openssl/doc/man3/SSL_CTX_set0_CA_list.pod b/crypto/openssl/doc/man3/SSL_CTX_set0_CA_list.pod index 618bd73e0420..d7ed89775b2e 100644 --- a/crypto/openssl/doc/man3/SSL_CTX_set0_CA_list.pod +++ b/crypto/openssl/doc/man3/SSL_CTX_set0_CA_list.pod @@ -2,14 +2,32 @@ =head1 NAME -SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list, -SSL_CTX_get0_CA_list, SSL_add1_to_CA_list, SSL_CTX_add1_to_CA_list, -SSL_get0_peer_CA_list - get or set CA list +SSL_CTX_set_client_CA_list, +SSL_set_client_CA_list, +SSL_get_client_CA_list, +SSL_CTX_get_client_CA_list, +SSL_CTX_add_client_CA, +SSL_add_client_CA, +SSL_set0_CA_list, +SSL_CTX_set0_CA_list, +SSL_get0_CA_list, +SSL_CTX_get0_CA_list, +SSL_add1_to_CA_list, +SSL_CTX_add1_to_CA_list, +SSL_get0_peer_CA_list +- get or set CA list =head1 SYNOPSIS #include <openssl/ssl.h> + void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); + void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); + STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); + STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); + int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); + int SSL_add_client_CA(SSL *ssl, X509 *cacert); + void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list); void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list); const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx); @@ -21,6 +39,70 @@ SSL_get0_peer_CA_list - get or set CA list =head1 DESCRIPTION +The functions described here set and manage the list of CA names that are sent +between two communicating peers. + +For TLS versions 1.2 and earlier the list of CA names is only sent from the +server to the client when requesting a client certificate. So any list of CA +names set is never sent from client to server and the list of CA names retrieved +by SSL_get0_peer_CA_list() is always B<NULL>. + +For TLS 1.3 the list of CA names is sent using the B<certificate_authorities> +extension and may be sent by a client (in the ClientHello message) or by +a server (when requesting a certificate). + +In most cases it is not necessary to set CA names on the client side. The list +of CA names that are acceptable to the client will be sent in plaintext to the +server. This has privacy implications and may also have performance implications +if the list is large. This optional capability was introduced as part of TLSv1.3 +and therefore setting CA names on the client side will have no impact if that +protocol version has been disabled. Most servers do not need this and so this +should be avoided unless required. + +The "client CA list" functions below only have an effect when called on the +server side. + +SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for B<ctx>. Ownership of B<list> is transferred +to B<ctx> and it should not be freed by the caller. + +SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for the chosen B<ssl>, overriding the +setting valid for B<ssl>'s SSL_CTX object. Ownership of B<list> is transferred +to B<s> and it should not be freed by the caller. + +SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for +B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed +by the caller. + +SSL_get_client_CA_list() returns the list of client CAs explicitly +set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with +SSL_CTX_set_client_CA_list(), when in server mode. In client mode, +SSL_get_client_CA_list returns the list of client CAs sent from the server, if +any. The returned list should not be freed by the caller. + +SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +B<ctx>. + +SSL_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. + +SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer +has sent. This can be called on either the server or the client side. The +returned list should not be freed by the caller. + +The "generic CA list" functions below are very similar to the "client CA +list" functions except that they have an effect on both the server and client +sides. The lists of CA names managed are separate - so you cannot (for example) +set CA names using the "client CA list" functions and then get them using the +"generic CA list" functions. Where a mix of the two types of functions has been +used on the server side then the "client CA list" functions take precedence. +Typically, on the server side, the "client CA list " functions should be used in +preference. As noted above in most cases it is not necessary to set CA names on +the client side. + SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and it should not be freed by the caller. @@ -30,10 +112,11 @@ overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of B<name_list> is transferred to B<s> and it should not be freed by the caller. SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for -B<ctx>. +B<ctx>. The returned list should not be freed by the caller. -SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for -B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. +SSL_get0_CA_list() retrieves any previously set list of CAs set for +B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. The +returned list should not be freed by the caller. SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the list of CAs sent to peer for B<ctx>. @@ -42,47 +125,60 @@ SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the list of CAs sent to the peer for B<s>, overriding the setting in the parent B<SSL_CTX>. -SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer -has sent. - =head1 NOTES -These functions are generalised versions of the client authentication -CA list functions such as L<SSL_CTX_set_client_CA_list(3)>. +When a TLS/SSL server requests a client certificate (see +B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which it will accept +certificates, to the client. -For TLS versions before 1.3 the list of CA names is only sent from the server -to client when requesting a client certificate. So any list of CA names set -is never sent from client to server and the list of CA names retrieved by -SSL_get0_peer_CA_list() is always B<NULL>. +This list must explicitly be set using SSL_CTX_set_client_CA_list() or +SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or +SSL_set0_CA_list() for the specific B<ssl>. The list specified +overrides the previous setting. The CAs listed do not become trusted (B<list> +only contains the names, not the complete certificates); use +L<SSL_CTX_load_verify_locations(3)> to additionally load them for verification. -For TLS 1.3 the list of CA names is sent using the B<certificate_authorities> -extension and will be sent by a client (in the ClientHello message) or by -a server (when requesting a certificate). +If the list of acceptable CAs is compiled in a file, the +L<SSL_load_client_CA_file(3)> function can be used to help to import the +necessary data. + +SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA() and +SSL_add1_to_CA_list() can be used to add additional items the list of CAs. If no +list was specified before using SSL_CTX_set_client_CA_list(), +SSL_CTX_set0_CA_list(), SSL_set_client_CA_list() or SSL_set0_CA_list(), a +new CA list for B<ctx> or B<ssl> (as appropriate) is opened. =head1 RETURN VALUES -SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value. +SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), +SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list() +and SSL_set0_CA_list() do not return a value. -SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA names -or B<NULL> is no CA names are set. +SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list() +and SSL_get0_CA_list() return a stack of CA names or B<NULL> is no CA names are +set. -SSL_CTX_add1_to_CA_list() and SSL_add1_to_CA_list() return 1 for success and 0 -for failure. +SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and +SSL_add1_to_CA_list() return 1 for success and 0 for failure. SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or B<NULL> or an empty stack if no list was sent. +=head1 EXAMPLES + +Scan all certificates in B<CAfile> and list them as acceptable CAs: + + SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); + =head1 SEE ALSO L<ssl(7)>, -L<SSL_CTX_set_client_CA_list(3)>, -L<SSL_get_client_CA_list(3)>, L<SSL_load_client_CA_file(3)>, L<SSL_CTX_load_verify_locations(3)> =head1 COPYRIGHT -Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/SSL_CTX_set1_curves.pod b/crypto/openssl/doc/man3/SSL_CTX_set1_curves.pod index a250f20c2206..7dca0e0161d9 100644 --- a/crypto/openssl/doc/man3/SSL_CTX_set1_curves.pod +++ b/crypto/openssl/doc/man3/SSL_CTX_set1_curves.pod @@ -32,6 +32,9 @@ SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve =head1 DESCRIPTION +For all of the functions below that set the supported groups there must be at +least one group in the list. + SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen> groups in the array B<glist>. The array consist of all NIDs of groups in preference order. For a TLS client the groups are used directly in the @@ -99,7 +102,7 @@ functions were first added to OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/SSL_CTX_set_client_CA_list.pod b/crypto/openssl/doc/man3/SSL_CTX_set_client_CA_list.pod deleted file mode 100644 index 76fd65e6fcaa..000000000000 --- a/crypto/openssl/doc/man3/SSL_CTX_set_client_CA_list.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, -SSL_add_client_CA - set list of CAs sent to the client when requesting a -client certificate - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); - void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); - int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); - int SSL_add_client_CA(SSL *ssl, X509 *cacert); - -=head1 DESCRIPTION - -SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for B<ctx>. - -SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for the chosen B<ssl>, overriding the -setting valid for B<ssl>'s SSL_CTX object. - -SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -B<ctx>. - -SSL_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. - -=head1 NOTES - -When a TLS/SSL server requests a client certificate (see -B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which -it will accept certificates, to the client. - -This list must explicitly be set using SSL_CTX_set_client_CA_list() for -B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list -specified overrides the previous setting. The CAs listed do not become -trusted (B<list> only contains the names, not the complete certificates); use -L<SSL_CTX_load_verify_locations(3)> -to additionally load them for verification. - -If the list of acceptable CAs is compiled in a file, the -L<SSL_load_client_CA_file(3)> -function can be used to help importing the necessary data. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional -items the list of client CAs. If no list was specified before using -SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client -CA list for B<ctx> or B<ssl> (as appropriate) is opened. - -These functions are only useful for TLS/SSL servers. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item Z<>0 - -A failure while manipulating the STACK_OF(X509_NAME) object occurred or -the X509_NAME could not be extracted from B<cacert>. Check the error stack -to find out the reason. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 EXAMPLES - -Scan all certificates in B<CAfile> and list them as acceptable CAs: - - SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); - -=head1 SEE ALSO - -L<ssl(7)>, -L<SSL_get_client_CA_list(3)>, -L<SSL_load_client_CA_file(3)>, -L<SSL_CTX_load_verify_locations(3)> - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/crypto/openssl/doc/man3/SSL_CTX_set_quiet_shutdown.pod b/crypto/openssl/doc/man3/SSL_CTX_set_quiet_shutdown.pod index 99922eb5bf8d..8ed9315df5c4 100644 --- a/crypto/openssl/doc/man3/SSL_CTX_set_quiet_shutdown.pod +++ b/crypto/openssl/doc/man3/SSL_CTX_set_quiet_shutdown.pod @@ -33,7 +33,7 @@ SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>. =head1 NOTES Normally when a SSL connection is finished, the parties must send out -"close notify" alert messages using L<SSL_shutdown(3)> +close_notify alert messages using L<SSL_shutdown(3)> for a clean shutdown. When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)> @@ -41,7 +41,7 @@ will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. (L<SSL_shutdown(3)> then behaves like L<SSL_set_shutdown(3)> called with SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.) -The session is thus considered to be shutdown, but no "close notify" alert +The session is thus considered to be shutdown, but no close_notify alert is sent to the peer. This behaviour violates the TLS standard. The default is normal shutdown behaviour as described by the TLS standard. @@ -62,7 +62,7 @@ L<SSL_clear(3)>, L<SSL_free(3)> =head1 COPYRIGHT -Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/SSL_get_client_CA_list.pod b/crypto/openssl/doc/man3/SSL_get_client_CA_list.pod deleted file mode 100644 index 40c3561efcee..000000000000 --- a/crypto/openssl/doc/man3/SSL_get_client_CA_list.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); - STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for -B<ctx> using L<SSL_CTX_set_client_CA_list(3)>. - -SSL_get_client_CA_list() returns the list of client CAs explicitly -set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with -L<SSL_CTX_set_client_CA_list(3)>, when in -server mode. In client mode, SSL_get_client_CA_list returns the list of -client CAs sent from the server, if any. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item STACK_OF(X509_NAMES) - -List of CA names explicitly set (for B<ctx> or in server mode) or send -by the server (client mode). - -=item NULL - -No client CA list was explicitly set (for B<ctx> or in server mode) or -the server did not send a list of CAs (client mode). - -=back - -=head1 SEE ALSO - -L<ssl(7)>, -L<SSL_CTX_set_client_CA_list(3)>, -L<SSL_CTX_set_client_cert_cb(3)> - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/crypto/openssl/doc/man3/SSL_get_error.pod b/crypto/openssl/doc/man3/SSL_get_error.pod index 01446a24a1e1..b3ab50568731 100644 --- a/crypto/openssl/doc/man3/SSL_get_error.pod +++ b/crypto/openssl/doc/man3/SSL_get_error.pod @@ -39,7 +39,7 @@ if and only if B<ret E<gt> 0>. =item SSL_ERROR_ZERO_RETURN The TLS/SSL peer has closed the connection for writing by sending the -"close notify" alert. +close_notify alert. No more data can be read. Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily indicate that the underlying transport has been closed. diff --git a/crypto/openssl/doc/man3/SSL_get_peer_signature_nid.pod b/crypto/openssl/doc/man3/SSL_get_peer_signature_nid.pod index ce6ab61f5e11..dbca8cffb920 100644 --- a/crypto/openssl/doc/man3/SSL_get_peer_signature_nid.pod +++ b/crypto/openssl/doc/man3/SSL_get_peer_signature_nid.pod @@ -2,8 +2,9 @@ =head1 NAME -SSL_get_peer_signature_nid, SSL_get_peer_signature_type_nid - get TLS -message signing types +SSL_get_peer_signature_nid, SSL_get_peer_signature_type_nid, +SSL_get_signature_nid, SSL_get_signature_type_nid - get TLS message signing +types =head1 SYNOPSIS @@ -11,6 +12,8 @@ message signing types int SSL_get_peer_signature_nid(SSL *ssl, int *psig_nid); int SSL_get_peer_signature_type_nid(const SSL *ssl, int *psigtype_nid); + int SSL_get_signature_nid(SSL *ssl, int *psig_nid); + int SSL_get_signature_type_nid(const SSL *ssl, int *psigtype_nid); =head1 DESCRIPTION @@ -24,12 +27,15 @@ where it is B<EVP_PKEY_RSA_PSS>. To differentiate between B<rsa_pss_rsae_*> and B<rsa_pss_pss_*> signatures, it's necessary to check the type of public key in the peer's certificate. +SSL_get_signature_nid() and SSL_get_signature_type_nid() return the equivalent +information for the local end of the connection. + =head1 RETURN VALUES These functions return 1 for success and 0 for failure. There are several possible reasons for failure: the cipher suite has no signature (e.g. it uses RSA key exchange or is anonymous), the TLS version is below 1.2 or -the functions were called before the peer signed a message. +the functions were called too early, e.g. before the peer signed a message. =head1 SEE ALSO diff --git a/crypto/openssl/doc/man3/SSL_get_peer_tmp_key.pod b/crypto/openssl/doc/man3/SSL_get_peer_tmp_key.pod new file mode 100644 index 000000000000..a722a813bff8 --- /dev/null +++ b/crypto/openssl/doc/man3/SSL_get_peer_tmp_key.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_get_peer_tmp_key, SSL_get_server_tmp_key, SSL_get_tmp_key - get information +about temporary keys used during a handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_peer_tmp_key(SSL *ssl, EVP_PKEY **key); + long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key); + long SSL_get_tmp_key(SSL *ssl, EVP_PKEY **key); + +=head1 DESCRIPTION + +SSL_get_peer_tmp_key() returns the temporary key provided by the peer and +used during key exchange. For example, if ECDHE is in use, then this represents +the peer's public ECDHE key. On success a pointer to the key is stored in +B<*key>. It is the caller's responsibility to free this key after use using +L<EVP_PKEY_free(3)>. + +SSL_get_server_tmp_key() is a backwards compatibility alias for +SSL_get_peer_tmp_key(). +Under that name it worked just on the client side of the connection, its +behaviour on the server end is release-dependent. + +SSL_get_tmp_key() returns the equivalent information for the local +end of the connection. + +=head1 RETURN VALUES + +All these functions return 1 on success and 0 otherwise. + +=head1 NOTES + +This function is implemented as a macro. + +=head1 SEE ALSO + +L<ssl(7)>, L<EVP_PKEY_free(3)> + +=head1 COPYRIGHT + +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/crypto/openssl/doc/man3/SSL_get_server_tmp_key.pod b/crypto/openssl/doc/man3/SSL_get_server_tmp_key.pod deleted file mode 100644 index fda891b7a837..000000000000 --- a/crypto/openssl/doc/man3/SSL_get_server_tmp_key.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_server_tmp_key - get information about the server's temporary key used -during a handshake - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key); - -=head1 DESCRIPTION - -SSL_get_server_tmp_key() returns the temporary key provided by the server and -used during key exchange. For example, if ECDHE is in use, then this represents -the server's public ECDHE key. On success a pointer to the key is stored in -B<*key>. It is the caller's responsibility to free this key after use using -L<EVP_PKEY_free(3)>. This function may only be called by the client. - -=head1 RETURN VALUES - -SSL_get_server_tmp_key() returns 1 on success or 0 otherwise. - -=head1 NOTES - -This function is implemented as a macro. - -=head1 SEE ALSO - -L<ssl(7)>, L<EVP_PKEY_free(3)> - -=head1 COPYRIGHT - -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/crypto/openssl/doc/man3/SSL_set_bio.pod b/crypto/openssl/doc/man3/SSL_set_bio.pod index 01617521bf52..1fa0d3492600 100644 --- a/crypto/openssl/doc/man3/SSL_set_bio.pod +++ b/crypto/openssl/doc/man3/SSL_set_bio.pod @@ -90,7 +90,7 @@ use SSL_set0_rbio() and SSL_set0_wbio() instead. =head1 RETURN VALUES -SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail. +SSL_set_bio(), SSL_set0_rbio() and SSL_set0_wbio() cannot fail. =head1 SEE ALSO @@ -104,7 +104,7 @@ SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/SSL_set_shutdown.pod b/crypto/openssl/doc/man3/SSL_set_shutdown.pod index 04bcc47814e3..b1cf58920be4 100644 --- a/crypto/openssl/doc/man3/SSL_set_shutdown.pod +++ b/crypto/openssl/doc/man3/SSL_set_shutdown.pod @@ -30,12 +30,12 @@ No shutdown setting, yet. =item SSL_SENT_SHUTDOWN -A "close notify" shutdown alert was sent to the peer, the connection is being +A close_notify shutdown alert was sent to the peer, the connection is being considered closed and the session is closed and correct. =item SSL_RECEIVED_SHUTDOWN -A shutdown alert was received form the peer, either a normal "close notify" +A shutdown alert was received form the peer, either a normal close_notify or a fatal error. =back @@ -47,13 +47,13 @@ the ssl session. If the session is still open, when L<SSL_clear(3)> or L<SSL_free(3)> is called, it is considered bad and removed according to RFC2246. The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN -(according to the TLS RFC, it is acceptable to only send the "close notify" +(according to the TLS RFC, it is acceptable to only send the close_notify alert but to not wait for the peer's answer, when the underlying connection is closed). SSL_set_shutdown() can be used to set this state without sending a close alert to the peer (see L<SSL_shutdown(3)>). -If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set, +If a close_notify was received, SSL_RECEIVED_SHUTDOWN will be set, for setting SSL_SENT_SHUTDOWN the application must however still call L<SSL_shutdown(3)> or SSL_set_shutdown() itself. @@ -71,7 +71,7 @@ L<SSL_clear(3)>, L<SSL_free(3)> =head1 COPYRIGHT -Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/crypto/openssl/doc/man3/SSL_shutdown.pod b/crypto/openssl/doc/man3/SSL_shutdown.pod index 453853d672fc..0a3d6d370d8b 100644 --- a/crypto/openssl/doc/man3/SSL_shutdown.pod +++ b/crypto/openssl/doc/man3/SSL_shutdown.pod @@ -13,27 +13,36 @@ SSL_shutdown - shut down a TLS/SSL connection =head1 DESCRIPTION SSL_shutdown() shuts down an active TLS/SSL connection. It sends the -"close notify" shutdown alert to the peer. +close_notify shutdown alert to the peer. =head1 NOTES -SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. +SSL_shutdown() tries to send the close_notify shutdown alert to the peer. Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and a currently open session is considered closed and good and will be kept in the session cache for further reuse. -The shutdown procedure consists of 2 steps: the sending of the "close notify" -shutdown alert and the reception of the peer's "close notify" shutdown -alert. According to the TLS standard, it is acceptable for an application -to only send its shutdown alert and then close the underlying connection -without waiting for the peer's response (this way resources can be saved, -as the process can already terminate or serve another connection). -When the underlying connection shall be used for more communications, the -complete shutdown procedure (bidirectional "close notify" alerts) must be -performed, so that the peers stay synchronized. +The shutdown procedure consists of two steps: sending of the close_notify +shutdown alert, and reception of the peer's close_notify shutdown alert. +The order of those two steps depends on the application. + +It is acceptable for an application to only send its shutdown alert and +then close the underlying connection without waiting for the peer's response. +This way resources can be saved, as the process can already terminate or +serve another connection. +This should only be done when it is known that the other side will not send more +data, otherwise there is a risk of a truncation attack. -SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step -behaviour. +When a client only writes and never reads from the connection, and the server +has sent a session ticket to establish a session, the client might not be able +to resume the session because it did not received and process the session ticket +from the server. +In case the application wants to be able to resume the session, it is recommended to +do a complete shutdown procedure (bidirectional close_notify alerts). + +When the underlying connection shall be used for more communications, the +complete shutdown procedure must be performed, so that the peers stay +synchronized. SSL_shutdown() only closes the write direction. It is not possible to call SSL_write() after calling SSL_shutdown(). @@ -41,45 +50,43 @@ The read direction is closed by the peer. =head2 First to close the connection -When the application is the first party to send the "close notify" +When the application is the first party to send the close_notify alert, SSL_shutdown() will only send the alert and then set the SSL_SENT_SHUTDOWN flag (so that the session is considered good and will be kept in the cache). -SSL_shutdown() will then return with 0. +If successful, SSL_shutdown() will return 0. + If a unidirectional shutdown is enough (the underlying connection shall be -closed anyway), this first call to SSL_shutdown() is sufficient. +closed anyway), this first successful call to SSL_shutdown() is sufficient. In order to complete the bidirectional shutdown handshake, the peer needs -to send back a "close notify" alert. +to send back a close_notify alert. The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing it. -SSL_shutdown() will return 1 when it has been received. -The peer is still allowed to send data after receiving the "close notify" +The peer is still allowed to send data after receiving the close_notify event. -If the peer did send data it needs to be processed by calling SSL_read() -before calling SSL_shutdown() a second time. +When it is done sending data, it will send the close_notify alert. +SSL_read() should be called until all data is received. SSL_read() will indicate the end of the peer data by returning <= 0 and SSL_get_error() returning SSL_ERROR_ZERO_RETURN. -It is recommended to call SSL_read() between SSL_shutdown() calls. =head2 Peer closes the connection -If the peer already sent the "close notify" alert B<and> it was +If the peer already sent the close_notify alert B<and> it was already processed implicitly inside another function (L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. SSL_read() will return <= 0 in that case, and SSL_get_error() will return SSL_ERROR_ZERO_RETURN. -SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN -flag and will immediately return with 1. +SSL_shutdown() will send the close_notify alert, set the SSL_SENT_SHUTDOWN +flag. +If successful, SSL_shutdown() will return 1. + Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. =head1 NOTES -It is recommended to do a bidirectional shutdown by checking the return value -of SSL_shutdown() and call it again until it returns 1 or a fatal error. - The behaviour of SSL_shutdown() additionally depends on the underlying BIO. If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the handshake step has been finished or an error occurred. @@ -95,8 +102,13 @@ nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. +After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again +to wait for the peer's close_notify alert. +SSL_shutdown() will return 1 in that case. +However, it is recommended to wait for it using SSL_read() instead. + SSL_shutdown() can be modified to only set the connection to "shutdown" -state but not actually send the "close notify" alert messages, +state but not actually send the close_notify alert messages, see L<SSL_CTX_set_quiet_shutdown(3)>. When "quiet shutdown" is enabled, SSL_shutdown() will always succeed and return 1. @@ -109,16 +121,16 @@ The following return values can occur: =item Z<>0 -The shutdown is not yet finished: the "close notify" was send but the peer +The shutdown is not yet finished: the close_notify was sent but the peer did not send it back yet. -Call SSL_shutdown() again to do a bidirectional shutdown. +Call SSL_read() to do a bidirectional shutdown. The output of L<SSL_get_error(3)> may be misleading, as an erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. =item Z<>1 -The shutdown was successfully completed. The "close notify" alert was sent -and the peer's "close notify" alert was received. +The shutdown was successfully completed. The close_notify alert was sent +and the peer's close_notify alert was received. =item E<lt>0 diff --git a/crypto/openssl/doc/man7/RAND_DRBG.pod b/crypto/openssl/doc/man7/RAND_DRBG.pod index b89c30d43edd..ba457f050483 100644 --- a/crypto/openssl/doc/man7/RAND_DRBG.pod +++ b/crypto/openssl/doc/man7/RAND_DRBG.pod @@ -189,7 +189,7 @@ In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG with fresh entropy by setting the I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>. -The dcoument [NIST SP 800-90C] describes prediction resistance requests +The document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. Since the default DRBG implementation does not have access to such an approved |