diff options
Diffstat (limited to 'doc')
31 files changed, 308 insertions, 178 deletions
diff --git a/doc/apps/cms.pod b/doc/apps/cms.pod index 4a7783d..dd6ae6e 100644 --- a/doc/apps/cms.pod +++ b/doc/apps/cms.pod @@ -335,6 +335,9 @@ When encrypting a message this option may be used multiple times to specify each recipient. This form B<must> be used if customised parameters are required (for example to specify RSA-OAEP). +Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this +option. + =item B<-keyid> use subject key identifier to identify certificates instead of issuer name and @@ -648,17 +651,14 @@ No revocation checking is done on the signer's certificate. =head1 HISTORY The use of multiple B<-signer> options and the B<-resign> command were first -added in OpenSSL 1.0.0 - -The B<keyopt> option was first added in OpenSSL 1.1.0 +added in OpenSSL 1.0.0. -The use of B<-recip> to specify the recipient when encrypting mail was first -added to OpenSSL 1.1.0 +The B<keyopt> option was first added in OpenSSL 1.0.2. -Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. +Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.0.2. The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added -to OpenSSL 1.1.0. +to OpenSSL 1.0.2. The -no_alt_chains options was first added to OpenSSL 1.0.2b. diff --git a/doc/apps/config.pod b/doc/apps/config.pod index 3f607d3..b1300a9 100644 --- a/doc/apps/config.pod +++ b/doc/apps/config.pod @@ -21,7 +21,7 @@ started or end of file is reached. A section name can consist of alphanumeric characters and underscores. The first section of a configuration file is special and is referred -to as the B<default> section this is usually unnamed and is from the +to as the B<default> section. This section is usually unnamed and spans from the start of file until the first named section. When a name is being looked up it is first looked up in a named section (if any) and then the default section. diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod index cdced1c..92efbf4 100644 --- a/doc/apps/crl.pod +++ b/doc/apps/crl.pod @@ -115,7 +115,7 @@ Convert a CRL file from PEM to DER: Output the text form of a DER encoded certificate: - openssl crl -in crl.der -text -noout + openssl crl -in crl.der -inform DER -text -noout =head1 BUGS diff --git a/doc/apps/genpkey.pod b/doc/apps/genpkey.pod index 4d09fc0..2e24400 100644 --- a/doc/apps/genpkey.pod +++ b/doc/apps/genpkey.pod @@ -11,7 +11,7 @@ B<openssl> B<genpkey> [B<-out filename>] [B<-outform PEM|DER>] [B<-pass arg>] -[B<-cipher>] +[B<-I<cipher>>] [B<-engine id>] [B<-paramfile file>] [B<-algorithm alg>] @@ -34,21 +34,21 @@ used. =item B<-outform DER|PEM> -This specifies the output format DER or PEM. +This specifies the output format DER or PEM. The default format is PEM. =item B<-pass arg> -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. +The output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. -=item B<-cipher> +=item B<-I<cipher>> This option encrypts the private key with the supplied cipher. Any algorithm name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. =item B<-engine id> -specifying an engine (by its unique B<id> string) will cause B<genpkey> +Specifying an engine (by its unique B<id> string) will cause B<genpkey> to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. If used this option should precede all other @@ -56,20 +56,33 @@ options. =item B<-algorithm alg> -public key algorithm to use such as RSA, DSA or DH. If used this option must +Public key algorithm to use such as RSA, DSA or DH. If used this option must precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> -are mutually exclusive. +are mutually exclusive. Engines may add algorithms in addition to the standard +built-in ones. + +Valid built-in algorithm names for private key generation are RSA and EC. + +Valid built-in algorithm names for parameter generation (see the B<-genparam> +option) are DH, DSA and EC. + +Note that the algorithm name X9.42 DH may be used as a synonym for the DH +algorithm. These are identical and do not indicate the type of parameters that +will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3 +or X9.42 DH parameters are required. See L<DH Parameter Generation Options> +below for more details. =item B<-pkeyopt opt:value> -set the public key algorithm option B<opt> to B<value>. The precise set of +Set the public key algorithm option B<opt> to B<value>. The precise set of options supported depends on the public key algorithm used and its -implementation. See B<KEY GENERATION OPTIONS> below for more details. +implementation. See L<KEY GENERATION OPTIONS> and +L<PARAMETER GENERATION OPTIONS> below for more details. =item B<-genparam> -generate a set of parameters instead of a private key. If used this option must -precede and B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. +Generate a set of parameters instead of a private key. If used this option must +precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. =item B<-paramfile filename> @@ -92,7 +105,7 @@ The options supported by each algorith and indeed each implementation of an algorithm can vary. The options for the OpenSSL implementations are detailed below. -=head1 RSA KEY GENERATION OPTIONS +=head2 RSA Key Generation Options =over 4 @@ -107,48 +120,92 @@ hexadecimal value if preceded by B<0x>. Default value is 65537. =back -=head1 DSA PARAMETER GENERATION OPTIONS +=head2 EC Key Generation Options + +The EC key generation options can also be used for parameter generation. + +=over 4 + +=item B<ec_paramgen_curve:curve> + +The EC curve to use. OpenSSL supports NIST curve names such as "P-256". + +=item B<ec_param_enc:encoding> + +The encoding to use for parameters. The "encoding" parameter must be either +"named_curve" or "explicit". The default value is "named_curve". + +=back + +=head1 PARAMETER GENERATION OPTIONS + +The options supported by each algorithm and indeed each implementation of an +algorithm can vary. The options for the OpenSSL implementations are detailed +below. + +=head2 DSA Parameter Generation Options =over 4 =item B<dsa_paramgen_bits:numbits> -The number of bits in the generated parameters. If not specified 1024 is used. +The number of bits in the generated prime. If not specified 1024 is used. + +=item B<dsa_paramgen_q_bits:numbits> + +The number of bits in the q parameter. Must be one of 160, 224 or 256. If not +specified 160 is used. + +=item B<dsa_paramgen_md:digest> + +The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> +or B<sha256>. If set, then the number of bits in B<q> will match the output size +of the specified digest and the B<dsa_paramgen_q_bits> parameter will be +ignored. If not set, then a digest will be used that gives an output matching +the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 +or B<sha256> if it is 256. =back -=head1 DH PARAMETER GENERATION OPTIONS +=head2 DH Parameter Generation Options =over 4 =item B<dh_paramgen_prime_len:numbits> -The number of bits in the prime parameter B<p>. +The number of bits in the prime parameter B<p>. The default is 1024. + +=item B<dh_paramgen_subprime_len:numbits> + +The number of bits in the sub prime parameter B<q>. The default is 256 if the +prime is at least 2048 bits long or 160 otherwise. Only relevant if used in +conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters. =item B<dh_paramgen_generator:value> -The value to use for the generator B<g>. +The value to use for the generator B<g>. The default is 2. + +=item B<dh_paramgen_type:value> + +The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH. +The default is 0. =item B<dh_rfc5114:num> -If this option is set then the appropriate RFC5114 parameters are used +If this option is set, then the appropriate RFC5114 parameters are used instead of generating new parameters. The value B<num> can take the values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of 1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections -2.1, 2.2 and 2.3 respectively. +2.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter +options. =back -=head1 EC PARAMETER GENERATION OPTIONS - -=over 4 - -=item B<ec_paramgen_curve:curve> - -the EC curve to use. +=head2 EC Parameter Generation Options -=back +The EC parameter generation options are the same as for key generation. See +L<EC Key Generation Options> above. =head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS @@ -179,8 +236,6 @@ numeric OID. Following parameter sets are supported: =back - - =head1 NOTES The use of the genpkey program is encouraged over the algorithm specific @@ -202,19 +257,25 @@ Generate a 2048 bit RSA key using 3 as the public exponent: openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ -pkeyopt rsa_keygen_pubexp:3 -Generate 1024 bit DSA parameters: +Generate 2048 bit DSA parameters: openssl genpkey -genparam -algorithm DSA -out dsap.pem \ - -pkeyopt dsa_paramgen_bits:1024 + -pkeyopt dsa_paramgen_bits:2048 Generate DSA key from parameters: openssl genpkey -paramfile dsap.pem -out dsakey.pem -Generate 1024 bit DH parameters: +Generate 2048 bit DH parameters: openssl genpkey -genparam -algorithm DH -out dhp.pem \ - -pkeyopt dh_paramgen_prime_len:1024 + -pkeyopt dh_paramgen_prime_len:2048 + +Generate 2048 bit X9.42 DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhpx.pem \ + -pkeyopt dh_paramgen_prime_len:2048 \ + -pkeyopt dh_paramgen_type:1 Output RFC5114 2048 bit DH parameters with 224 bit subgroup: @@ -224,6 +285,16 @@ Generate DH key from parameters: openssl genpkey -paramfile dhp.pem -out dhkey.pem +Generate EC key directly: + + openssl genpkey -algorithm EC -out eckey.pem \ + -pkeyopt ec_paramgen_curve:P-384 \ + -pkeyopt ec_param_enc:named_curve + +=head1 HISTORY + +The ability to use NIST curve names, and to generate an EC key directly, +were added in OpenSSL 1.0.2. =cut diff --git a/doc/apps/req.pod b/doc/apps/req.pod index 20b2f39..01c1c2e 100644 --- a/doc/apps/req.pod +++ b/doc/apps/req.pod @@ -393,8 +393,7 @@ option. For compatibility B<encrypt_rsa_key> is an equivalent option. =item B<default_md> This option specifies the digest algorithm to use. Possible values -include B<md5 sha1 mdc2>. If not present then MD5 is used. This -option can be overridden on the command line. +include B<md5 sha1 mdc2>. This option can be overridden on the command line. =item B<string_mask> diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index d2cad29..77cc071 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -141,8 +141,9 @@ pauses 1 second between each read and write call. =item B<-showcerts> -display the whole server certificate chain: normally only the server -certificate itself is displayed. +Displays the server certificate list as sent by the server: it only consists of +certificates the server has sent (in the order the server has sent them). It is +B<not> a verified chain. =item B<-prexit> @@ -354,7 +355,8 @@ a client certificate. Therefor merely including a client certificate on the command line is no guarantee that the certificate works. If there are problems verifying a server certificate then the -B<-showcerts> option can be used to show the whole chain. +B<-showcerts> option can be used to show all the certificates sent by the +server. Since the SSLv23 client hello cannot include compression methods or extensions these will only be supported if its use is disabled, for example by using the diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod index 9916fc3..84777ee 100644 --- a/doc/apps/s_server.pod +++ b/doc/apps/s_server.pod @@ -49,6 +49,7 @@ B<openssl> B<s_server> [B<-no_ssl3>] [B<-no_tls1>] [B<-no_dhe>] +[B<-no_ecdhe>] [B<-bugs>] [B<-hack>] [B<-www>] @@ -144,6 +145,11 @@ a static set of parameters hard coded into the s_server program will be used. if this option is set then no DH parameters will be loaded effectively disabling the ephemeral DH cipher suites. +=item B<-no_ecdhe> + +if this option is set then no ECDH parameters will be selected, effectively +disabling the ephemeral ECDH cipher suites. + =item B<-no_tmp_rsa> certain export cipher suites sometimes use a temporary RSA key, this option diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod index b1de1d1..2830134 100644 --- a/doc/crypto/BIO_s_fd.pod +++ b/doc/crypto/BIO_s_fd.pod @@ -60,7 +60,7 @@ BIO_s_fd() returns the file descriptor BIO method. BIO_reset() returns zero for success and -1 if an error occurred. BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() +if an error occurred. These values reflect the underlying lseek() behaviour. BIO_set_fd() always returns 1. diff --git a/doc/crypto/BN_add.pod b/doc/crypto/BN_add.pod index 88c7a79..02e5486 100644 --- a/doc/crypto/BN_add.pod +++ b/doc/crypto/BN_add.pod @@ -91,7 +91,9 @@ BN_exp() raises I<a> to the I<p>-th power and places the result in I<r> BN_mul(). BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p % -m>). This function uses less time and space than BN_exp(). +m>). This function uses less time and space than BN_exp(). Do not call this +function when B<m> is even and any of the parameters have the +B<BN_FLG_CONSTTIME> flag set. BN_gcd() computes the greatest common divisor of I<a> and I<b> and places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or diff --git a/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod index f6bb484..075aec3 100644 --- a/doc/crypto/BN_bn2bin.pod +++ b/doc/crypto/BN_bn2bin.pod @@ -39,8 +39,8 @@ numbers, the string is prefaced with a leading '-'. The string must be freed later using OPENSSL_free(). BN_hex2bn() converts the string B<str> containing a hexadecimal number -to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new -B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's +to a B<BIGNUM> and stores it in **B<a>. If *B<a> is NULL, a new +B<BIGNUM> is created. If B<a> is NULL, it only computes the number's length in hexadecimal digits. If the string starts with '-', the number is negative. A "negative zero" is converted to zero. diff --git a/doc/crypto/BN_generate_prime.pod b/doc/crypto/BN_generate_prime.pod index bf1b530..003d123 100644 --- a/doc/crypto/BN_generate_prime.pod +++ b/doc/crypto/BN_generate_prime.pod @@ -90,7 +90,17 @@ If B<do_trial_division == 0>, this test is skipped. Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin probabilistic primality test with B<nchecks> iterations. If B<nchecks == BN_prime_checks>, a number of iterations is used that -yields a false positive rate of at most 2^-80 for random input. +yields a false positive rate of at most 2^-64 for random input. +The error rate depends on the size of the prime and goes down for bigger primes. +The rate is 2^-80 starting at 308 bits, 2^-112 at 852 bits, 2^-128 at 1080 bits, +2^-192 at 3747 bits and 2^-256 at 6394 bits. + +When the source of the prime is not random or not trusted, the number +of checks needs to be much higher to reach the same level of assurance: +It should equal half of the targeted security level in bits (rounded up to the +next integer if necessary). +For instance, to reach the 128 bit security level, B<nchecks> should be set to +64. If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called after the j-th iteration (j = 0, 1, ...). B<ctx> is a diff --git a/doc/crypto/CMS_encrypt.pod b/doc/crypto/CMS_encrypt.pod index 1ee5b27..88e44d4 100644 --- a/doc/crypto/CMS_encrypt.pod +++ b/doc/crypto/CMS_encrypt.pod @@ -18,9 +18,8 @@ B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. =head1 NOTES -Only certificates carrying RSA keys are supported so the recipient certificates -supplied to this function must all contain RSA public keys, though they do not -have to be signed using the RSA algorithm. +Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this +function. EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because most clients will support it. diff --git a/doc/crypto/CMS_get0_SignerInfos.pod b/doc/crypto/CMS_get0_SignerInfos.pod index b46c0e0..69fde81 100644 --- a/doc/crypto/CMS_get0_SignerInfos.pod +++ b/doc/crypto/CMS_get0_SignerInfos.pod @@ -51,7 +51,7 @@ CMS_SignerInfo_set1_signer_cert(). Once all signer certificates have been set CMS_verify() can be used. -Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if +Although CMS_get0_SignerInfos() can return NULL if an error occurs B<or> if there are no signers this is not a problem in practice because the only error which can occur is if the B<cms> structure is not of type signedData due to application error. diff --git a/doc/crypto/CMS_get1_ReceiptRequest.pod b/doc/crypto/CMS_get1_ReceiptRequest.pod index f546376..7a483ec 100644 --- a/doc/crypto/CMS_get1_ReceiptRequest.pod +++ b/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -48,7 +48,7 @@ CMS_verify(). CMS_ReceiptRequest_create0() returns a signed receipt request structure or NULL if an error occurred. -CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. +CMS_add1_ReceiptRequest() returns 1 for success or 0 if an error occurred. CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and decoded. It returns 0 if a signed receipt request is not present and -1 if diff --git a/doc/crypto/DSA_do_sign.pod b/doc/crypto/DSA_do_sign.pod index 5dfc733..340d195 100644 --- a/doc/crypto/DSA_do_sign.pod +++ b/doc/crypto/DSA_do_sign.pod @@ -20,8 +20,8 @@ digest B<dgst> using the private key B<dsa> and returns it in a newly allocated B<DSA_SIG> structure. L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part -of the signing operation in case signature generation is -time-critical. +of the signing operation for each signature in case signature generation +is time-critical. DSA_do_verify() verifies that the signature B<sig> matches a given message digest B<dgst> of size B<len>. B<dsa> is the signer's public diff --git a/doc/crypto/DSA_sign.pod b/doc/crypto/DSA_sign.pod index 97389e8..cd45ec5 100644 --- a/doc/crypto/DSA_sign.pod +++ b/doc/crypto/DSA_sign.pod @@ -31,6 +31,10 @@ in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing the old ones unless *B<kinvp> and *B<rp> are NULL. These values may be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. B<ctx> is a pre-allocated B<BN_CTX> or NULL. +The precomputed values from DSA_sign_setup() B<MUST NOT be used> for +more than one signature: using the same B<dsa-E<gt>kinv> and +B<dsa-E<gt>r> pair twice under the same private key on different +plaintexts will result in permanently exposing the DSA private key. DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> matches a given message digest B<dgst> of size B<len>. diff --git a/doc/crypto/EVP_DigestSignInit.pod b/doc/crypto/EVP_DigestSignInit.pod index 83e6589..7a3e84d 100644 --- a/doc/crypto/EVP_DigestSignInit.pod +++ b/doc/crypto/EVP_DigestSignInit.pod @@ -19,9 +19,12 @@ The EVP signature routines are a high level interface to digital signatures. EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with -EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can -be used to set alternative signing options. +be used to set alternative signing options. Note that any existing value in +B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed +directly by the application (it will be freed automatically when the EVP_MD_CTX +is freed). The digest B<type> may be NULL if the signing algorithm supports it. EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the signature context B<ctx>. This function can be called several times on the diff --git a/doc/crypto/EVP_DigestVerifyInit.pod b/doc/crypto/EVP_DigestVerifyInit.pod index 347c511..2e2c0fd 100644 --- a/doc/crypto/EVP_DigestVerifyInit.pod +++ b/doc/crypto/EVP_DigestVerifyInit.pod @@ -19,9 +19,12 @@ The EVP signature routines are a high level interface to digital signatures. EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized -with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL, the EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this -can be used to set alternative verification options. +can be used to set alternative verification options. Note that any existing +value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be +freed directly by the application (it will be freed automatically when the +EVP_MD_CTX is freed). EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the verification context B<ctx>. This function can be called several times on the diff --git a/doc/crypto/EVP_PKEY_verify_recover.pod b/doc/crypto/EVP_PKEY_verify_recover.pod index 399120e..23a28a9 100644 --- a/doc/crypto/EVP_PKEY_verify_recover.pod +++ b/doc/crypto/EVP_PKEY_verify_recover.pod @@ -29,7 +29,7 @@ B<rout> and the amount of data written to B<routlen>. =head1 NOTES Normally an application is only interested in whether a signature verification -operation is successful in those cases the EVP_verify() function should be +operation is successful in those cases the EVP_verify() function should be used. Sometimes however it is useful to obtain the data originally signed using a @@ -58,7 +58,7 @@ Recover digest originally signed using PKCS#1 and SHA256 digest: EVP_PKEY_CTX *ctx; unsigned char *rout, *sig; - size_t routlen, siglen; + size_t routlen, siglen; EVP_PKEY *verify_key; /* NB: assumes verify_key, sig and siglen are already set up * and that verify_key is an RSA public key @@ -94,7 +94,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> =head1 HISTORY diff --git a/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod index b8d2896..c870bd4 100644 --- a/doc/crypto/OBJ_nid2obj.pod +++ b/doc/crypto/OBJ_nid2obj.pod @@ -42,7 +42,7 @@ constants. OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to an ASN1_OBJECT structure, its long name and its short name respectively, -or B<NULL> is an error occurred. +or B<NULL> if an error occurred. OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID for the object B<o>, the long name <ln> or the short name <sn> respectively diff --git a/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/doc/crypto/OPENSSL_VERSION_NUMBER.pod index f7ca7cb..02eabd7 100644 --- a/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ b/doc/crypto/OPENSSL_VERSION_NUMBER.pod @@ -2,12 +2,14 @@ =head1 NAME -OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number +OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_TEXT, SSLeay, SSLeay_version +- 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> long SSLeay(void); @@ -43,9 +45,12 @@ 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. - For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. +OPENSSL_VERSION_TEXT is the text variant of the version number and the +release date. For example, +"OpenSSL 1.0.1a 15 Oct 2015". + SSLeay() returns this number. The return value can be compared to the macro to make sure that the correct version of the library has been loaded, especially when using DLLs on Windows systems. diff --git a/doc/crypto/SMIME_read_PKCS7.pod b/doc/crypto/SMIME_read_PKCS7.pod index 9d46715..7cdca1e 100644 --- a/doc/crypto/SMIME_read_PKCS7.pod +++ b/doc/crypto/SMIME_read_PKCS7.pod @@ -57,7 +57,7 @@ streaming single pass option should be available. =head1 RETURN VALUES SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL> -is an error occurred. The error can be obtained from ERR_get_error(3). +if an error occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO diff --git a/doc/crypto/ecdsa.pod b/doc/crypto/ecdsa.pod index 46c071b..5708d90 100644 --- a/doc/crypto/ecdsa.pod +++ b/doc/crypto/ecdsa.pod @@ -112,6 +112,8 @@ using the public key B<eckey>. =head1 RETURN VALUES +ECDSA_SIG_new() returns NULL if the allocation fails. + ECDSA_size() returns the maximum length signature or 0 on error. ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 diff --git a/doc/crypto/pem.pod b/doc/crypto/pem.pod index 763eb6f..de9ecca 100644 --- a/doc/crypto/pem.pod +++ b/doc/crypto/pem.pod @@ -342,7 +342,7 @@ for it twice) if B<rwflag> is 1. The B<u> parameter has the same value as the B<u> parameter passed to the PEM routine. It allows arbitrary data to be passed to the callback by the application (for example a window handle in a GUI application). The callback -B<must> return the number of characters in the passphrase or 0 if +B<must> return the number of characters in the passphrase or -1 if an error occurred. =head1 EXAMPLES @@ -354,84 +354,77 @@ Read a certificate in PEM format from a BIO: X509 *x; x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) - { - /* Error */ - } + if (x == NULL) { + /* Error */ + } Alternative method: X509 *x = NULL; - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) - { - /* Error */ - } + if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { + /* Error */ + } Write a certificate to a BIO: - if (!PEM_write_bio_X509(bp, x)) - { - /* Error */ - } + if (!PEM_write_bio_X509(bp, x)) { + /* Error */ + } Write an unencrypted private key to a FILE pointer: - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) - { - /* Error */ - } + if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { + /* Error */ + } Write a private key (using traditional format) to a BIO using triple DES encryption, the pass phrase is prompted for: - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) - { - /* Error */ - } + if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) { + /* Error */ + } Write a private key (using PKCS#8 format) to a BIO using triple DES encryption, using the pass phrase "hello": - if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) - { - /* Error */ - } + if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) { + /* Error */ + } Read a private key from a BIO using the pass phrase "hello": key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) - { - /* Error */ - } + if (key == NULL) { + /* Error */ + } Read a private key from a BIO using a pass phrase callback: key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) - { - /* Error */ - } + if (key == NULL) { + /* Error */ + } Skeleton pass phrase callback: - int pass_cb(char *buf, int size, int rwflag, void *u); - { - int len; - char *tmp; - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - - if (len <= 0) return 0; - /* if too long, truncate */ - if (len > size) len = size; - memcpy(buf, tmp, len); - return len; - } + int pass_cb(char *buf, int size, int rwflag, void *u) + { + + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", u); + + /* get pass phrase, length 'len' into 'tmp' */ + char *tmp = "hello"; + if (tmp == NULL) /* An error occurred */ + return -1; + + size_t len = strlen(tmp); + + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; + } =head1 NOTES diff --git a/doc/fingerprints.txt b/doc/fingerprints.txt index 373e90d..2cb74ae 100644 --- a/doc/fingerprints.txt +++ b/doc/fingerprints.txt @@ -1,63 +1,24 @@ - Fingerprints +Fingerprints for Signing Releases -OpenSSL releases are signed with PGP/GnuPG keys. You can find the -signatures in separate files in the same location you find the -distributions themselves. The normal file name is the same as the -distribution file, with '.asc' added. For example, the signature for -the distribution of OpenSSL 1.0.1h, openssl-1.0.1h.tar.gz, is found in -the file openssl-1.0.1h.tar.gz.asc. +OpenSSL releases are signed with PGP/GnuPG keys. This file contains +the fingerprints of team members who are "authorized" to sign the +next release. + +The signature is a detached cleartxt signature, with the same name +as the release but with ".asc" appended. For example, release +1.0.1h can be found in openssl-1.0.1h.tar.gz with the signature +in the file named openssl-1.0.1h.tar.gz.asc. The following is the list of fingerprints for the keys that are currently in use to sign OpenSSL distributions: -pub 1024D/F709453B 2003-10-20 - Key fingerprint = C4CA B749 C34F 7F4C C04F DAC9 A7AF 9E78 F709 453B -uid Richard Levitte <richard@levitte.org> +pub 4096R/7DF9EE8C 2014-10-04 + Key fingerprint = 7953 AC1F BC3D C8B3 B292 393E D5E9 E43F 7DF9 EE8C +uid Richard Levitte <richard@opensslfoundation.com> uid Richard Levitte <levitte@openssl.org> -uid Richard Levitte <levitte@lp.se> - -pub 2048R/F295C759 1998-12-13 - Key fingerprint = D0 5D 8C 61 6E 27 E6 60 41 EC B1 B8 D5 7E E5 97 -uid Dr S N Henson <shenson@drh-consultancy.demon.co.uk> - -pub 4096R/FA40E9E2 2005-03-19 - Key fingerprint = 6260 5AA4 334A F9F0 DDE5 D349 D357 7507 FA40 E9E2 -uid Dr Stephen Henson <shenson@opensslfoundation.com> -uid Dr Stephen Henson <shenson@drh-consultancy.co.uk> -uid Dr Stephen N Henson <steve@openssl.org> -sub 4096R/8811F530 2005-03-19 - -pub 1024R/49A563D9 1997-02-24 - Key fingerprint = 7B 79 19 FA 71 6B 87 25 0E 77 21 E5 52 D9 83 BF -uid Mark Cox <mjc@redhat.com> -uid Mark Cox <mark@awe.com> -uid Mark Cox <mjc@apache.org> - -pub 1024R/9C58A66D 1997-04-03 - Key fingerprint = 13 D0 B8 9D 37 30 C3 ED AC 9C 24 7D 45 8C 17 67 -uid jaenicke@openssl.org -uid Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE> - -pub 1024D/2118CF83 1998-07-13 - Key fingerprint = 7656 55DE 62E3 96FF 2587 EB6C 4F6D E156 2118 CF83 -uid Ben Laurie <ben@thebunker.net> -uid Ben Laurie <ben@cryptix.org> -uid Ben Laurie <ben@algroup.co.uk> -sub 4096g/1F5143E7 1998-07-13 - -pub 1024R/5A6A9B85 1994-03-22 - Key fingerprint = C7 AC 7E AD 56 6A 65 EC F6 16 66 83 7E 86 68 28 -uid Bodo Moeller <2005@bmoeller.de> -uid Bodo Moeller <2003@bmoeller.de> -uid Bodo Moeller <2004@bmoeller.de> -uid Bodo Moeller <bmoeller@acm.org> -uid Bodo Moeller <bodo@openssl.org> -uid Bodo Moeller <bm@ulf.mali.sub.org> -uid Bodo Moeller <3moeller@informatik.uni-hamburg.de> -uid Bodo Moeller <Bodo_Moeller@public.uni-hamburg.de> -uid Bodo Moeller <3moeller@rzdspc5.informatik.uni-hamburg.de> +uid Richard Levitte <richard@openssl.com> pub 2048R/0E604491 2013-04-30 Key fingerprint = 8657 ABB2 60F0 56B1 E519 0839 D9C4 D26D 0E60 4491 +uid Matt Caswell <matt@openssl.org> uid Matt Caswell <frodo@baggins.org> - diff --git a/doc/man3/X509_cmp_time.pod b/doc/man3/X509_cmp_time.pod new file mode 100644 index 0000000..5bf5111 --- /dev/null +++ b/doc/man3/X509_cmp_time.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +X509_cmp_time - X509 time functions + +=head1 SYNOPSIS + + X509_cmp_time(const ASN1_TIME *asn1_time, time_t *cmp_time); + +=head1 DESCRIPTION + +X509_cmp_time() compares the ASN1_TIME in B<asn1_time> with the time in +<cmp_time>. + +B<asn1_time> must satisfy the ASN1_TIME format mandated by RFC 5280, i.e., +its format must be either YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ. + +If B<cmp_time> is NULL the current time is used. + +=head1 BUGS + +Unlike many standard comparison functions, X509_cmp_time returns 0 on error. + +=head1 RETURN VALUES + +X509_cmp_time() returns -1 if B<asn1_time> is earlier than, or equal to, +B<cmp_time>, and 1 otherwise. It returns 0 on error. + +=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/doc/ssl/SSL_CTX_use_certificate.pod b/doc/ssl/SSL_CTX_use_certificate.pod index 80321b8..800423e 100644 --- a/doc/ssl/SSL_CTX_use_certificate.pod +++ b/doc/ssl/SSL_CTX_use_certificate.pod @@ -142,6 +142,13 @@ L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>. of view, it however does not make sense as the data in the certificate is considered public anyway.) +All of the functions to set a new certificate will replace any existing +certificate of the same type that has already been set. Similarly all of the +functions to set a new private key will replace any private key that has already +been set. Applications should call L<SSL_CTX_check_private_key(3)> or +L<SSL_check_private_key(3)> as appropriate after loading a new certificate and +private key to confirm that the certificate and key match. + =head1 RETURN VALUES On success, the functions return 1. diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod index aecadd9..7697d27 100644 --- a/doc/ssl/SSL_get_ciphers.pod +++ b/doc/ssl/SSL_get_ciphers.pod @@ -2,7 +2,10 @@ =head1 NAME -SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs +SSL_get_ciphers, +SSL_get_cipher_list, +SSL_get_shared_ciphers +- get list of available SSL_CIPHERs =head1 SYNOPSIS @@ -10,6 +13,7 @@ SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); const char *SSL_get_cipher_list(const SSL *ssl, int priority); + char *SSL_get_shared_ciphers(const SSL *s, char *buf, int size); =head1 DESCRIPTION @@ -22,6 +26,19 @@ listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are available, or there are less ciphers than B<priority> available, NULL is returned. +SSL_get_shared_ciphers() creates a colon separated and NUL terminated list of +SSL_CIPHER names that are available in both the client and the server. B<buf> is +the buffer that should be populated with the list of names and B<size> is the +size of that buffer. A pointer to B<buf> is returned on success or NULL on +error. If the supplied buffer is not large enough to contain the complete list +of names then a truncated list of names will be returned. Note that just because +a ciphersuite is available (i.e. it is configured in the cipher list) and shared +by both the client and the server it does not mean that it is enabled (for +example some ciphers may not be usable by a server if there is not a suitable +certificate configured). This function will return available shared ciphersuites +whether or not they are enabled. This is a server side function only and must +only be called after the completion of the initial handshake. + =head1 NOTES The details of the ciphers obtained by SSL_get_ciphers() can be obtained using diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod index 0c41caa..921d316 100644 --- a/doc/ssl/SSL_get_session.pod +++ b/doc/ssl/SSL_get_session.pod @@ -28,6 +28,11 @@ count of the B<SSL_SESSION> is incremented by one. The ssl session contains all information required to re-establish the connection without a new handshake. +A session will be automatically removed from the session cache and marked as +non-resumable if the connection is not closed down cleanly, e.g. if a fatal +error occurs on the connection or L<SSL_shutdown(3)> is not called prior to +L<SSL_free(3)>. + SSL_get0_session() returns a pointer to the actual session. As the reference counter is not incremented, the pointer is only valid while the connection is in use. If L<SSL_clear(3)|SSL_clear(3)> or diff --git a/doc/ssl/SSL_get_version.pod b/doc/ssl/SSL_get_version.pod index 9ae6f25..f0c696c 100644 --- a/doc/ssl/SSL_get_version.pod +++ b/doc/ssl/SSL_get_version.pod @@ -13,7 +13,9 @@ SSL_get_version - get the protocol version of a connection. =head1 DESCRIPTION SSL_get_version() returns the name of the protocol used for the -connection B<ssl>. +connection B<ssl>. It should only be called after the initial handshake has been +completed. Prior to that the results returned from this function may be +unreliable. =head1 RETURN VALUES @@ -43,7 +45,7 @@ The connection uses the TLSv1.2 protocol. =item unknown -This indicates that no version has been set (no connection established). +This indicates an unknown protocol version. =back diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 70cca17..5408d61 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -572,7 +572,7 @@ connection defined in the B<SSL> structure. =item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); -=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); +=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int size); =item int B<SSL_get_shutdown>(const SSL *ssl); |