diff options
Diffstat (limited to 'crypto/openssl/doc')
95 files changed, 1285 insertions, 458 deletions
diff --git a/crypto/openssl/doc/HOWTO/certificates.txt b/crypto/openssl/doc/HOWTO/certificates.txt index a8a34c7abc51..65f8fc8296cd 100644 --- a/crypto/openssl/doc/HOWTO/certificates.txt +++ b/crypto/openssl/doc/HOWTO/certificates.txt @@ -3,22 +3,22 @@ 1. Introduction -How you handle certificates depend a great deal on what your role is. +How you handle certificates depends a great deal on what your role is. Your role can be one or several of: - - User of some client software - - User of some server software + - User of some client application + - User of some server application - Certificate authority This file is for users who wish to get a certificate of their own. -Certificate authorities should read ca.txt. +Certificate authorities should read https://www.openssl.org/docs/apps/ca.html. In all the cases shown below, the standard configuration file, as compiled into openssl, will be used. You may find it in /etc/, -/usr/local/ssl/ or somewhere else. The name is openssl.cnf, and -is better described in another HOWTO <config.txt?>. If you want to -use a different configuration file, use the argument '-config {file}' -with the command shown below. +/usr/local/ssl/ or somewhere else. By default the file is named +openssl.cnf and is described at https://www.openssl.org/docs/apps/config.html. +You can specify a different configuration file using the +'-config {file}' argument with the commands shown below. 2. Relationship with keys @@ -29,24 +29,26 @@ somewhere. With OpenSSL, public keys are easily derived from private keys, so before you create a certificate or a certificate request, you need to create a private key. -Private keys are generated with 'openssl genrsa' if you want a RSA -private key, or 'openssl gendsa' if you want a DSA private key. -Further information on how to create private keys can be found in -another HOWTO <keys.txt?>. The rest of this text assumes you have -a private key in the file privkey.pem. +Private keys are generated with 'openssl genrsa -out privkey.pem' if +you want a RSA private key, or if you want a DSA private key: +'openssl dsaparam -out dsaparam.pem 2048; openssl gendsa -out privkey.pem dsaparam.pem'. + +The private keys created by these commands are not passphrase protected; +it might or might not be the desirable thing. Further information on how to +create private keys can be found at https://www.openssl.org/docs/HOWTO/keys.txt. +The rest of this text assumes you have a private key in the file privkey.pem. 3. Creating a certificate request -To create a certificate, you need to start with a certificate -request (or, as some certificate authorities like to put -it, "certificate signing request", since that's exactly what they do, -they sign it and give you the result back, thus making it authentic -according to their policies). A certificate request can then be sent -to a certificate authority to get it signed into a certificate, or if -you have your own certificate authority, you may sign it yourself, or -if you need a self-signed certificate (because you just want a test -certificate or because you are setting up your own CA). +To create a certificate, you need to start with a certificate request +(or, as some certificate authorities like to put it, "certificate +signing request", since that's exactly what they do, they sign it and +give you the result back, thus making it authentic according to their +policies). A certificate request is sent to a certificate authority +to get it signed into a certificate. You can also sign the certificate +yourself if you have your own certificate authority or create a +self-signed certificate (typically for testing purpose). The certificate request is created like this: @@ -55,12 +57,14 @@ The certificate request is created like this: Now, cert.csr can be sent to the certificate authority, if they can handle files in PEM format. If not, use the extra argument '-outform' followed by the keyword for the format to use (see another HOWTO -<formats.txt?>). In some cases, that isn't sufficient and you will -have to be more creative. +<formats.txt?>). In some cases, -outform does not let you output the +certificate request in the right format and you will have to use one +of the various other commands that are exposed by openssl (or get +creative and use a combination of tools). -When the certificate authority has then done the checks the need to -do (and probably gotten payment from you), they will hand over your -new certificate to you. +The certificate authority performs various checks (according to their +policies) and usually waits for payment from you. Once that is +complete, they send you your new certificate. Section 5 will tell you more on how to handle the certificate you received. @@ -68,11 +72,12 @@ received. 4. Creating a self-signed test certificate -If you don't want to deal with another certificate authority, or just -want to create a test certificate for yourself. This is similar to -creating a certificate request, but creates a certificate instead of -a certificate request. This is NOT the recommended way to create a -CA certificate, see ca.txt. +You can create a self-signed certificate if you don't want to deal +with a certificate authority, or if you just want to create a test +certificate for yourself. This is similar to creating a certificate +request, but creates a certificate instead of a certificate request. +This is NOT the recommended way to create a CA certificate, see +https://www.openssl.org/docs/apps/ca.html. openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095 @@ -93,13 +98,13 @@ certificate and your key to various formats, most often also putting them together into one file. The ways to do this is described in another HOWTO <formats.txt?>, I will just mention the simplest case. In the case of a raw DER thing in PEM format, and assuming that's all -right for yor applications, simply concatenating the certificate and +right for your applications, simply concatenating the certificate and the key into a new file and using that one should be enough. With some applications, you don't even have to do that. -By now, you have your cetificate and your private key and can start -using the software that depend on it. +By now, you have your certificate and your private key and can start +using applications that depend on it. -- Richard Levitte diff --git a/crypto/openssl/doc/HOWTO/proxy_certificates.txt b/crypto/openssl/doc/HOWTO/proxy_certificates.txt index f98ec3607678..d78be2f142bf 100644 --- a/crypto/openssl/doc/HOWTO/proxy_certificates.txt +++ b/crypto/openssl/doc/HOWTO/proxy_certificates.txt @@ -1,74 +1,69 @@ -<DRAFT!> HOWTO proxy certificates 0. WARNING -NONE OF THE CODE PRESENTED HERE HAVE BEEN CHECKED! They are just an -example to show you how things can be done. There may be typos or -type conflicts, and you will have to resolve them. +NONE OF THE CODE PRESENTED HERE HAS BEEN CHECKED! The code is just examples to +show you how things could be done. There might be typos or type conflicts, and +you will have to resolve them. 1. Introduction -Proxy certificates are defined in RFC 3820. They are really usual -certificates with the mandatory extension proxyCertInfo. +Proxy certificates are defined in RFC 3820. They are really usual certificates +with the mandatory extension proxyCertInfo. -Proxy certificates are issued by an End Entity (typically a user), -either directly with the EE certificate as issuing certificate, or by -extension through an already issued proxy certificate.. They are used -to extend rights to some other entity (a computer process, typically, -or sometimes to the user itself), so it can perform operations in the -name of the owner of the EE certificate. +Proxy certificates are issued by an End Entity (typically a user), either +directly with the EE certificate as issuing certificate, or by extension through +an already issued proxy certificate. Proxy certificates are used to extend +rights to some other entity (a computer process, typically, or sometimes to the +user itself). This allows the entity to perform operations on behalf of the +owner of the EE certificate. See http://www.ietf.org/rfc/rfc3820.txt for more information. 2. A warning about proxy certificates -Noone seems to have tested proxy certificates with security in mind. -Basically, to this date, it seems that proxy certificates have only -been used in a world that's highly aware of them. What would happen -if an unsuspecting application is to validate a chain of certificates -that contains proxy certificates? It would usually consider the leaf -to be the certificate to check for authorisation data, and since proxy -certificates are controlled by the EE certificate owner alone, it's -would be normal to consider what the EE certificate owner could do -with them. +No one seems to have tested proxy certificates with security in mind. To this +date, it seems that proxy certificates have only been used in a context highly +aware of them. -subjectAltName and issuerAltName are forbidden in proxy certificates, -and this is enforced in OpenSSL. The subject must be the same as the -issuer, with one commonName added on. +Existing applications might misbehave when trying to validate a chain of +certificates which use a proxy certificate. They might incorrectly consider the +leaf to be the certificate to check for authorisation data, which is controlled +by the EE certificate owner. -Possible threats are, as far as has been imagined so far: +subjectAltName and issuerAltName are forbidden in proxy certificates, and this +is enforced in OpenSSL. The subject must be the same as the issuer, with one +commonName added on. + +Possible threats we can think of at this time include: - impersonation through commonName (think server certificates). - - use of additional extensions, possibly non-standard ones used in - certain environments, that would grant extra or different - authorisation rights. + - use of additional extensions, possibly non-standard ones used in certain + environments, that would grant extra or different authorisation rights. + +For these reasons, OpenSSL requires that the use of proxy certificates be +explicitly allowed. Currently, this can be done using the following methods: -For this reason, OpenSSL requires that the use of proxy certificates -be explicitely allowed. Currently, this can be done using the -following methods: + - if the application directly calls X509_verify_cert(), it can first call: - - if the application calls X509_verify_cert() itself, it can do the - following prior to that call (ctx is the pointer passed in the call - to X509_verify_cert()): + X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); - X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); + Where ctx is the pointer which then gets passed to X509_verify_cert(). - - in all other cases, proxy certificate validation can be enabled - before starting the application by setting the envirnoment variable - OPENSSL_ALLOW_PROXY_CERTS with some non-empty value. + - proxy certificate validation can be enabled before starting the application + by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS. -There are thoughts to allow proxy certificates with a line in the -default openssl.cnf, but that's still in the future. +In the future, it might be possible to enable proxy certificates by editing +openssl.cnf. -3. How to create proxy cerificates +3. How to create proxy certificates -It's quite easy to create proxy certificates, by taking advantage of -the lack of checks of the 'openssl x509' application (*ahem*). But -first, you need to create a configuration section that contains a -definition of the proxyCertInfo extension, a little like this: +Creating proxy certificates is quite easy, by taking advantage of a lack of +checks in the 'openssl x509' application (*ahem*). You must first create a +configuration section that contains a definition of the proxyCertInfo extension, +for example: [ v3_proxy ] # A proxy certificate MUST NEVER be a CA certificate. @@ -77,10 +72,10 @@ definition of the proxyCertInfo extension, a little like this: # Usual authority key ID authorityKeyIdentifier=keyid,issuer:always - # Now, for the extension that marks this certificate as a proxy one + # The extension which marks this certificate as a proxy proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB -It's also possible to give the proxy extension in a separate section: +It's also possible to specify the proxy extension in a separate section: proxyCertInfo=critical,@proxy_ext @@ -89,96 +84,85 @@ It's also possible to give the proxy extension in a separate section: pathlen=0 policy=text:BC -The policy value has a specific syntax, {syntag}:{string}, where the -syntag determines what will be done with the string. The recognised -syntags are as follows: - - text indicates that the string is simply the bytes, not - encoded in any kind of way: +The policy value has a specific syntax, {syntag}:{string}, where the syntag +determines what will be done with the string. The following syntags are +recognised: - policy=text:räksmörgås + text indicates that the string is simply bytes, without any encoding: - Previous versions of this design had a specific tag - for UTF-8 text. However, since the bytes are copied - as-is anyway, there's no need for it. Instead, use - the text: tag, like this: + policy=text:räksmörgÃ¥s - policy=text:räksmörgÃ¥s + Previous versions of this design had a specific tag for UTF-8 text. + However, since the bytes are copied as-is anyway, there is no need for + such a specific tag. - hex indicates the string is encoded in hex, with colons - between each byte (every second hex digit): + hex indicates the string is encoded in hex, with colons between each byte + (every second hex digit): - policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 + policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 - Previous versions of this design had a tag to insert a - complete DER blob. However, the only legal use for - this would be to surround the bytes that would go with - the hex: tag with what's needed to construct a correct - OCTET STRING. Since hex: does that, the DER tag felt - superfluous, and was therefore removed. + Previous versions of this design had a tag to insert a complete DER + blob. However, the only legal use for this would be to surround the + bytes that would go with the hex: tag with whatever is needed to + construct a correct OCTET STRING. The DER tag therefore felt + superfluous, and was removed. - file indicates that the text of the policy should really be - taken from a file. The string is then really a file - name. This is useful for policies that are large - (more than a few of lines) XML documents, for example. + file indicates that the text of the policy should really be taken from a + file. The string is then really a file name. This is useful for + policies that are large (more than a few lines, e.g. XML documents). The 'policy' setting can be split up in multiple lines like this: 0.policy=This is - 1.polisy= a multi- + 1.policy= a multi- 2.policy=line policy. -NOTE: the proxy policy value is the part that determines the rights -granted to the process using the proxy certificate. The value is -completely dependent on the application reading and interpretting it! +NOTE: the proxy policy value is the part which determines the rights granted to +the process using the proxy certificate. The value is completely dependent on +the application reading and interpreting it! -Now that you have created an extension section for your proxy -certificate, you can now easily create a proxy certificate like this: +Now that you have created an extension section for your proxy certificate, you +can easily create a proxy certificate by doing: - openssl req -new -config openssl.cnf \ - -out proxy.req -keyout proxy.key - openssl x509 -req -CAcreateserial -in proxy.req -days 7 \ - -out proxy.crt -CA user.crt -CAkey user.key \ - -extfile openssl.cnf -extensions v3_proxy + openssl req -new -config openssl.cnf -out proxy.req -keyout proxy.key + openssl x509 -req -CAcreateserial -in proxy.req -days 7 -out proxy.crt \ + -CA user.crt -CAkey user.key -extfile openssl.cnf -extensions v3_proxy -It's just as easy to create a proxy certificate using another proxy -certificate as issuer (note that I'm using a different configuration -section for it): +You can also create a proxy certificate using another proxy certificate as +issuer (note: I'm using a different configuration section for it): - openssl req -new -config openssl.cnf \ - -out proxy2.req -keyout proxy2.key - openssl x509 -req -CAcreateserial -in proxy2.req -days 7 \ - -out proxy2.crt -CA proxy.crt -CAkey proxy.key \ - -extfile openssl.cnf -extensions v3_proxy2 + openssl req -new -config openssl.cnf -out proxy2.req -keyout proxy2.key + openssl x509 -req -CAcreateserial -in proxy2.req -days 7 -out proxy2.crt \ + -CA proxy.crt -CAkey proxy.key -extfile openssl.cnf -extensions v3_proxy2 4. How to have your application interpret the policy? -The basic way to interpret proxy policies is to prepare some default -rights, then do a check of the proxy certificate against the a chain -of proxy certificates, user certificate and CA certificates, and see -what rights came out by the end. Sounds easy, huh? It almost is. +The basic way to interpret proxy policies is to start with some default rights, +then compute the resulting rights by checking the proxy certificate against +the chain of proxy certificates, user certificate and CA certificates. You then +use the final computed rights. Sounds easy, huh? It almost is. -The slightly complicated part is how to pass data between your +The slightly complicated part is figuring out how to pass data between your application and the certificate validation procedure. You need the following ingredients: - - a callback routing that will be called for every certificate that's - validated. It will be called several times for each certificates, - so you must be attentive to when it's a good time to do the proxy - policy interpretation and check, as well as to fill in the defaults - when the EE certificate is checked. + - a callback function that will be called for every certificate being + validated. The callback be called several times for each certificate, + so you must be careful to do the proxy policy interpretation at the right + time. You also need to fill in the defaults when the EE certificate is + checked. - - a structure of data that's shared between your application code and - the callback. + - a data structure that is shared between your application code and the + callback. - a wrapper function that sets it all up. - - an ex_data index function that creates an index into the generic - ex_data store that's attached to an X509 validation context. + - an ex_data index function that creates an index into the generic ex_data + store that is attached to an X509 validation context. -This is some cookbook code for you to fill in: +Here is some skeleton code you can fill in: /* In this example, I will use a view of granted rights as a bit array, one bit for each possible right. */ @@ -210,7 +194,7 @@ This is some cookbook code for you to fill in: static int verify_callback(int ok, X509_STORE_CTX *ctx) { if (ok == 1) /* It's REALLY important you keep the proxy policy - check within this secion. It's important to know + check within this section. It's important to know that when ok is 1, the certificates are checked from top to bottom. You get the CA root first, followed by the possible chain of intermediate @@ -221,7 +205,7 @@ This is some cookbook code for you to fill in: if (xs->ex_flags & EXFLAG_PROXY) { - YOUR_RIGHTS *rights = + YOUR_RIGHTS *rights = (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, get_proxy_auth_ex_data_idx()); PROXY_CERT_INFO_EXTENSION *pci = @@ -250,12 +234,12 @@ This is some cookbook code for you to fill in: bit array and fill it with the rights granted by the current proxy certificate, then use it as a mask on the accumulated rights bit array, and - voilà, you now have a new accumulated rights bit + voilà , you now have a new accumulated rights bit array. */ { int i; YOUR_RIGHTS tmp_rights; - memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights)); + memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights)); /* process_rights() is supposed to be a procedure that takes a string and it's length, interprets @@ -276,7 +260,7 @@ This is some cookbook code for you to fill in: { /* We have a EE certificate, let's use it to set default! */ - YOUR_RIGHTS *rights = + YOUR_RIGHTS *rights = (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, get_proxy_auth_ex_data_idx()); diff --git a/crypto/openssl/doc/apps/asn1parse.pod b/crypto/openssl/doc/apps/asn1parse.pod index f7bb92621168..76a765daf95b 100644 --- a/crypto/openssl/doc/apps/asn1parse.pod +++ b/crypto/openssl/doc/apps/asn1parse.pod @@ -15,6 +15,8 @@ B<openssl> B<asn1parse> [B<-length number>] [B<-i>] [B<-oid filename>] +[B<-dump>] +[B<-dlimit num>] [B<-strparse offset>] [B<-genstr string>] [B<-genconf file>] @@ -64,6 +66,14 @@ indents the output according to the "depth" of the structures. a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this file is described in the NOTES section below. +=item B<-dump> + +dump unknown data in hex format. + +=item B<-dlimit num> + +like B<-dump>, but only the first B<num> bytes are output. + =item B<-strparse offset> parse the contents octets of the ASN.1 object starting at B<offset>. This diff --git a/crypto/openssl/doc/apps/c_rehash.pod b/crypto/openssl/doc/apps/c_rehash.pod new file mode 100644 index 000000000000..c564e8631552 --- /dev/null +++ b/crypto/openssl/doc/apps/c_rehash.pod @@ -0,0 +1,81 @@ +=pod + +=for comment +Original text by James Westby, contributed under the OpenSSL license. + +=head1 NAME + +c_rehash - Create symbolic links to files named by the hash values + +=head1 SYNOPSIS + +B<c_rehash> +[ I<directory>...] + +=head1 DESCRIPTION + +B<c_rehash> scans directories and calculates a hash value of each C<.pem> +file in the specified directory list and creates symbolic links +for each file, where the name of the link is the hash value. +This utility is useful as many programs that use OpenSSL require +directories to be set up like this in order to find certificates. + +If any directories are named on the command line, then those are +processed in turn. If not, then the B<SSL_CERT_DIR> environment variable +is consulted; this shold be a colon-separated list of directories, +like the Unix B<PATH> variable. +If that is not set then the default directory (installation-specific +but often B</usr/local/ssl/certs>) is processed. + +In order for a directory to be processed, the user must have write +permissions on that directory, otherwise it will be skipped. +The links created are of the form C<HHHHHHHH.D>, where each B<H> +is a hexadecimal character and B<D> is a single decimal digit. +When processing a directory, B<c_rehash> will first remove all links +that have a name in that syntax. If you have links in that format +used for other purposes, they will be removed. +Hashes for CRL's look similar except the letter B<r> appears after +the period, like this: C<HHHHHHHH.rD>. + +Multiple objects may have the same hash; they will be indicated by +incrementing the B<D> value. Duplicates are found by comparing the +full SHA-1 fingerprint. A warning will be displayed if a duplicate +is found. + +A warning will also be displayed if there are B<.pem> files that +cannot be parsed as either a certificate or a CRL. + +The program uses the B<openssl> program to compute the hashes and +fingerprints. If not found in the user's B<PATH>, then set the +B<OPENSSL> environment variable to the full pathname. +Any program can be used, it will be invoked as follows for either +a certificate or CRL: + + $OPENSSL x509 -hash -fingerprint -noout -in FFFFFF + $OPENSSL crl -hash -fingerprint -noout -in FFFFFF + +where B<FFFFFF> is the filename. It must output the hash of the +file on the first line, and the fingerprint on the second, +optionally prefixed with some text and an equals sign. + +=head1 ENVIRONMENT + +=over + +=item B<OPENSSL> + +The path to an executable to use to generate hashes and +fingerprints (see above). + +=item B<SSL_CERT_DIR> + +Colon separated list of directories to operate on. +Ignored if directories are listed on the command line. + +=back + +=head1 SEE ALSO + +L<openssl(1)|openssl(1)>, +L<crl(1)|crl(1)>. +L<x509(1)|x509(1)>. diff --git a/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod index bcf4959f383a..f600f553b1a7 100644 --- a/crypto/openssl/doc/apps/ca.pod +++ b/crypto/openssl/doc/apps/ca.pod @@ -13,6 +13,8 @@ B<openssl> B<ca> [B<-name section>] [B<-gencrl>] [B<-revoke file>] +[B<-status serial>] +[B<-updatedb>] [B<-crl_reason reason>] [B<-crl_hold instruction>] [B<-crl_compromise time>] @@ -26,6 +28,7 @@ B<openssl> B<ca> [B<-md arg>] [B<-policy arg>] [B<-keyfile arg>] +[B<-keyform PEM|DER>] [B<-key arg>] [B<-passin arg>] [B<-cert file>] @@ -83,7 +86,7 @@ a single self signed certificate to be signed by the CA. a file containing a single Netscape signed public key and challenge and additional field values to be signed by the CA. See the B<SPKAC FORMAT> -section for information on the required format. +section for information on the required input and output format. =item B<-infiles> @@ -94,7 +97,7 @@ are assumed to be the names of files containing certificate requests. the output file to output certificates to. The default is standard output. The certificate details will also be printed out to this -file. +file in PEM format (except that B<-spkac> outputs DER format). =item B<-outdir directory> @@ -110,6 +113,11 @@ the CA certificate file. the private key to sign requests with. +=item B<-keyform PEM|DER> + +the format of the data in the private key file. +The default is PEM. + =item B<-key password> the password used to encrypt the private key. Since on some @@ -267,6 +275,15 @@ the number of hours before the next CRL is due. a filename containing a certificate to revoke. +=item B<-status serial> + +displays the revocation status of the certificate with the specified +serial number and exits. + +=item B<-updatedb> + +Updates the database index to purge expired certificates. + =item B<-crl_reason reason> revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>, @@ -499,6 +516,10 @@ the SPKAC and also the required DN components as name value pairs. If you need to include the same component twice then it can be preceded by a number and a '.'. +When processing SPKAC format, the output is DER if the B<-out> +flag is used, but PEM format if sending to stdout or the B<-outdir> +flag is used. + =head1 EXAMPLES Note: these examples assume that the B<ca> directory structure is diff --git a/crypto/openssl/doc/apps/ciphers.pod b/crypto/openssl/doc/apps/ciphers.pod index f44aa00a2fdb..6086d0a7154f 100644 --- a/crypto/openssl/doc/apps/ciphers.pod +++ b/crypto/openssl/doc/apps/ciphers.pod @@ -36,7 +36,7 @@ SSL v2 and for SSL v3/TLS v1. =item B<-V> -Like B<-V>, but include cipher suite codes in output (hex format). +Like B<-v>, but include cipher suite codes in output (hex format). =item B<-ssl3> @@ -116,8 +116,8 @@ specified. =item B<COMPLEMENTOFDEFAULT> the ciphers included in B<ALL>, but not enabled by default. Currently -this is B<ADH>. Note that this rule does not cover B<eNULL>, which is -not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). +this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>, +which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). =item B<ALL> @@ -165,21 +165,58 @@ included. =item B<aNULL> the cipher suites offering no authentication. This is currently the anonymous -DH algorithms. These cipher suites are vulnerable to a "man in the middle" -attack and so their use is normally discouraged. +DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable +to a "man in the middle" attack and so their use is normally discouraged. =item B<kRSA>, B<RSA> cipher suites using RSA key exchange. +=item B<kDHr>, B<kDHd>, B<kDH> + +cipher suites using DH key agreement and DH certificates signed by CAs with RSA +and DSS keys or either respectively. Not implemented. + =item B<kEDH> -cipher suites using ephemeral DH key agreement. +cipher suites using ephemeral DH key agreement, including anonymous cipher +suites. -=item B<kDHr>, B<kDHd> +=item B<EDH> -cipher suites using DH key agreement and DH certificates signed by CAs with RSA -and DSS keys respectively. Not implemented. +cipher suites using authenticated ephemeral DH key agreement. + +=item B<ADH> + +anonymous DH cipher suites, note that this does not include anonymous Elliptic +Curve DH (ECDH) cipher suites. + +=item B<DH> + +cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH. + +=item B<kECDHr>, B<kECDHe>, B<kECDH> + +cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA +keys or either respectively. + +=item B<kEECDH> + +cipher suites using ephemeral ECDH key agreement, including anonymous +cipher suites. + +=item B<EECDHE> + +cipher suites using authenticated ephemeral ECDH key agreement. + +=item B<AECDH> + +anonymous Elliptic Curve Diffie Hellman cipher suites. + +=item B<ECDH> + +cipher suites using ECDH key exchange, including anonymous, ephemeral and +fixed ECDH. =item B<aRSA> @@ -194,30 +231,39 @@ cipher suites using DSS authentication, i.e. the certificates carry DSS keys. cipher suites effectively using DH authentication, i.e. the certificates carry DH keys. Not implemented. +=item B<aECDH> + +cipher suites effectively using ECDH authentication, i.e. the certificates +carry ECDH keys. + +=item B<aECDSA>, B<ECDSA> + +cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA +keys. + =item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA> ciphers suites using FORTEZZA key exchange, authentication, encryption or all FORTEZZA algorithms. Not implemented. -=item B<TLSv1>, B<SSLv3>, B<SSLv2> - -TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. +=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2> -=item B<DH> - -cipher suites using DH, including anonymous DH. +TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note: +there are no ciphersuites specific to TLS v1.1. -=item B<ADH> +=item B<AES128>, B<AES256>, B<AES> -anonymous DH cipher suites. +cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES. -=item B<AES> +=item B<AESGCM> -cipher suites using AES. +AES in Galois Counter Mode (GCM): these ciphersuites are only supported +in TLS v1.2. -=item B<CAMELLIA> +=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA> -cipher suites using Camellia. +cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit +CAMELLIA. =item B<3DES> @@ -251,6 +297,10 @@ cipher suites using MD5. cipher suites using SHA1. +=item B<SHA256>, B<SHA384> + +ciphersuites using SHA256 or SHA384. + =item B<aGOST> cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction @@ -277,6 +327,9 @@ cipher suites, using HMAC based on GOST R 34.11-94. cipher suites using GOST 28147-89 MAC B<instead of> HMAC. +=item B<PSK> + +cipher suites using pre-shared keys (PSK). =back @@ -423,7 +476,100 @@ Note: these ciphers can also be used in SSL v3. TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA -=head2 SSL v2.0 cipher suites. +=head2 Elliptic curve cipher suites. + + TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA + TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA + TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA + TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA + TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA + + TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA + TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA + TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA + TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA + TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA + + TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA + TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA + TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA + TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA + TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA + + TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA + TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA + TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA + TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA + TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA + + TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA + TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA + TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA + TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA + TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA + +=head2 TLS v1.2 cipher suites + + TLS_RSA_WITH_NULL_SHA256 NULL-SHA256 + + TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256 + TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256 + TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256 + TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384 + + TLS_DH_RSA_WITH_AES_128_CBC_SHA256 Not implemented. + TLS_DH_RSA_WITH_AES_256_CBC_SHA256 Not implemented. + TLS_DH_RSA_WITH_AES_128_GCM_SHA256 Not implemented. + TLS_DH_RSA_WITH_AES_256_GCM_SHA384 Not implemented. + + TLS_DH_DSS_WITH_AES_128_CBC_SHA256 Not implemented. + TLS_DH_DSS_WITH_AES_256_CBC_SHA256 Not implemented. + TLS_DH_DSS_WITH_AES_128_GCM_SHA256 Not implemented. + TLS_DH_DSS_WITH_AES_256_GCM_SHA384 Not implemented. + + TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256 + TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256 + TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256 + TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384 + + TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256 + TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256 + TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256 + TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384 + + TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256 + TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384 + TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256 + TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384 + + TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256 + TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384 + TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256 + TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384 + + TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256 + TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384 + TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256 + TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384 + + TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256 + TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384 + TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256 + TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384 + + TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256 + TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256 + TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256 + TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384 + +=head2 Pre shared keying (PSK) cipheruites + + TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA + TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA + TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA + TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA + +=head2 Deprecated SSL v2.0 cipher suites. SSL_CK_RC4_128_WITH_MD5 RC4-MD5 SSL_CK_RC4_128_EXPORT40_WITH_MD5 EXP-RC4-MD5 @@ -452,6 +598,11 @@ strength: openssl ciphers -v 'ALL:!ADH:@STRENGTH' +Include all ciphers except ones with no encryption (eNULL) or no +authentication (aNULL): + + openssl ciphers -v 'ALL:!aNULL' + Include only 3DES ciphers and then place RSA ciphers last: openssl ciphers -v '3DES:+RSA' diff --git a/crypto/openssl/doc/apps/cms.pod b/crypto/openssl/doc/apps/cms.pod index a09588a18df4..75b698834a28 100644 --- a/crypto/openssl/doc/apps/cms.pod +++ b/crypto/openssl/doc/apps/cms.pod @@ -90,6 +90,11 @@ decrypt mail using the supplied certificate and private key. Expects an encrypted mail message in MIME format for the input file. The decrypted mail is written to the output file. +=item B<-debug_decrypt> + +this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used +with caution: see the notes section below. + =item B<-sign> sign mail using the supplied certificate and private key. Input file is @@ -138,7 +143,7 @@ output an error. =item B<-EncryptedData_encrypt> -Encrypt suppled content using supplied symmetric key and algorithm using a CMS +Encrypt content using supplied symmetric key and algorithm using a CMS B<EncrytedData> type and output the content. =item B<-sign_receipt> @@ -446,32 +451,42 @@ Streaming is always used for the B<-sign> operation with detached data but since the content is no longer part of the CMS structure the encoding remains DER. +If the B<-decrypt> option is used without a recipient certificate then an +attempt is made to locate the recipient by trying each potential recipient +in turn using the supplied private key. To thwart the MMA attack +(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are +tried whether they succeed or not and if no recipients match the message +is "decrypted" using a random key which will typically output garbage. +The B<-debug_decrypt> option can be used to disable the MMA attack protection +and return an error if no recipient can be found: this option should be used +with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>). + =head1 EXIT CODES =over 4 -=item 0 +=item Z<>0 the operation was completely successfully. -=item 1 +=item Z<>1 an error occurred parsing the command options. -=item 2 +=item Z<>2 one of the input files could not be read. -=item 3 +=item Z<>3 an error occurred creating the CMS file or when reading the MIME message. -=item 4 +=item Z<>4 an error occurred decrypting or verifying the message. -=item 5 +=item Z<>5 the message was verified correctly but an error occurred writing out the signers certificates. diff --git a/crypto/openssl/doc/apps/config.pod b/crypto/openssl/doc/apps/config.pod index d94b539e26ca..d9796c3c51cb 100644 --- a/crypto/openssl/doc/apps/config.pod +++ b/crypto/openssl/doc/apps/config.pod @@ -119,7 +119,7 @@ variable points to a section containing further ENGINE configuration information. The section pointed to by B<engines> is a table of engine names (though see -B<engine_id> below) and further sections containing configuration informations +B<engine_id> below) and further sections containing configuration information specific to each ENGINE. Each ENGINE specific section is used to set default algorithms, load diff --git a/crypto/openssl/doc/apps/crl.pod b/crypto/openssl/doc/apps/crl.pod index a40c873b9568..044a9da91545 100644 --- a/crypto/openssl/doc/apps/crl.pod +++ b/crypto/openssl/doc/apps/crl.pod @@ -12,6 +12,7 @@ B<openssl> B<crl> [B<-text>] [B<-in filename>] [B<-out filename>] +[B<-nameopt option>] [B<-noout>] [B<-hash>] [B<-issuer>] @@ -53,6 +54,11 @@ default. print out the CRL in text form. +=item B<-nameopt option> + +option which determines how the subject or issuer names are displayed. See +the description of B<-nameopt> in L<x509(1)|x509(1)>. + =item B<-noout> don't output the encoded version of the CRL. @@ -62,6 +68,11 @@ don't output the encoded version of the CRL. output a hash of the issuer name. This can be use to lookup CRLs in a directory by issuer name. +=item B<-hash_old> + +outputs the "hash" of the CRL issuer name using the older algorithm +as used by OpenSSL versions before 1.0.0. + =item B<-issuer> output the issuer name. diff --git a/crypto/openssl/doc/apps/dgst.pod b/crypto/openssl/doc/apps/dgst.pod index d79fb5cbc1c9..405847ad8cb1 100644 --- a/crypto/openssl/doc/apps/dgst.pod +++ b/crypto/openssl/doc/apps/dgst.pod @@ -2,16 +2,19 @@ =head1 NAME -dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests +dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests =head1 SYNOPSIS B<openssl> B<dgst> -[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>] +[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>] [B<-c>] [B<-d>] [B<-hex>] [B<-binary>] +[B<-r>] +[B<-hmac arg>] +[B<-non-fips-allow>] [B<-out filename>] [B<-sign filename>] [B<-keyform arg>] @@ -20,17 +23,19 @@ B<openssl> B<dgst> [B<-prverify filename>] [B<-signature filename>] [B<-hmac key>] +[B<-non-fips-allow>] +[B<-fips-fingerprint>] [B<file...>] -[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>] -[B<-c>] -[B<-d>] -[B<file...>] +B<openssl> +[I<digest>] +[B<...>] =head1 DESCRIPTION The digest functions output the message digest of a supplied file or files -in hexadecimal form. They can also be used for digital signing and verification. +in hexadecimal. The digest functions also generate and verify digital +signatures using message digests. =head1 OPTIONS @@ -48,12 +53,26 @@ print out BIO debugging information. =item B<-hex> digest is to be output as a hex dump. This is the default case for a "normal" -digest as opposed to a digital signature. +digest as opposed to a digital signature. See NOTES below for digital +signatures using B<-hex>. =item B<-binary> output the digest or signature in binary form. +=item B<-r> + +output the digest in the "coreutils" format used by programs like B<sha1sum>. + +=item B<-hmac arg> + +set the HMAC key to "arg". + +=item B<-non-fips-allow> + +Allow use of non FIPS digest when in FIPS mode. This has no effect when not in +FIPS mode. + =item B<-out filename> filename to output to, or standard output by default. @@ -64,8 +83,8 @@ digitally sign the digest using the private key in "filename". =item B<-keyform arg> -Specifies the key format to sign digest with. Only PEM and ENGINE -formats are supported by the B<dgst> command. +Specifies the key format to sign digest with. The DER, PEM, P12, +and ENGINE formats are supported. =item B<-engine id> @@ -117,7 +136,7 @@ Following options are supported by both by B<HMAC> and B<gost-mac>: =over 8 =item B<key:string> - + Specifies MAC key as alphnumeric string (use if key contain printable characters only). String length must conform to any restrictions of the MAC algorithm for example exactly 32 chars for gost-mac. @@ -138,6 +157,15 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-non-fips-allow> + +enable use of non-FIPS algorithms such as MD5 even in FIPS mode. + +=item B<-fips-fingerprint> + +compute HMAC using a specific key +for certain OpenSSL-FIPS operations. + =item B<file...> file or files to digest. If no files are specified then standard input is @@ -145,18 +173,41 @@ used. =back + +=head1 EXAMPLES + +To create a hex-encoded message digest of a file: + openssl dgst -md5 -hex file.txt + +To sign a file using SHA-256 with binary file output: + openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt + +To verify a signature: + openssl dgst -sha256 -verify publickey.pem \ + -signature signature.sign \ + file.txt + + =head1 NOTES The digest of choice for all new applications is SHA1. Other digests are however still widely used. -If you wish to sign or verify data using the DSA algorithm then the dss1 -digest must be used. +When signing a file, B<dgst> will automatically determine the algorithm +(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. +When verifying signatures, it only handles the RSA, DSA, or ECDSA signature +itself, not the related data to identify the signer and algorithm used in +formats such as x.509, CMS, and S/MIME. A source of random numbers is required for certain signing algorithms, in -particular DSA. +particular ECDSA and DSA. The signing and verify options should only be used if a single file is being signed or verified. +Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r" +or similar program to transform the hex signature into a binary signature +prior to verification. + + =cut diff --git a/crypto/openssl/doc/apps/dhparam.pod b/crypto/openssl/doc/apps/dhparam.pod index 9edb4ff4e1dd..6e27cf5c1516 100644 --- a/crypto/openssl/doc/apps/dhparam.pod +++ b/crypto/openssl/doc/apps/dhparam.pod @@ -12,6 +12,7 @@ B<openssl dhparam> [B<-in> I<filename>] [B<-out> I<filename>] [B<-dsaparam>] +[B<-check>] [B<-noout>] [B<-text>] [B<-C>] @@ -64,6 +65,10 @@ exchange more efficient. Beware that with such DSA-style DH parameters, a fresh DH key should be created for each use to avoid small-subgroup attacks that may be possible otherwise. +=item B<-check> + +check if the parameters are valid primes and generator. + =item B<-2>, B<-5> The generator to use, either 2 or 5. 2 is the default. If present then the diff --git a/crypto/openssl/doc/apps/dsa.pod b/crypto/openssl/doc/apps/dsa.pod index ddbc9327fabd..8bf6cc9dcad6 100644 --- a/crypto/openssl/doc/apps/dsa.pod +++ b/crypto/openssl/doc/apps/dsa.pod @@ -13,6 +13,12 @@ B<openssl> B<dsa> [B<-passin arg>] [B<-out filename>] [B<-passout arg>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] [B<-des>] [B<-des3>] [B<-idea>] @@ -74,10 +80,10 @@ filename. 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)>. -=item B<-des|-des3|-idea> +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +These options encrypt the private key with the specified +cipher before outputting it. A pass phrase is prompted for. If none of these options is specified the key is written in plain text. This means that using the B<dsa> utility to read in an encrypted key with no encryption option can be used to remove the pass phrase from a key, or by diff --git a/crypto/openssl/doc/apps/ec.pod b/crypto/openssl/doc/apps/ec.pod index ba6dc4689bf0..5c7b45d4e75e 100644 --- a/crypto/openssl/doc/apps/ec.pod +++ b/crypto/openssl/doc/apps/ec.pod @@ -41,7 +41,7 @@ PKCS#8 private key format use the B<pkcs8> command. This specifies the input format. The B<DER> option with a private key uses an ASN.1 DER encoded SEC1 private key. When used with a public key it -uses the SubjectPublicKeyInfo structur as specified in RFC 3280. +uses the SubjectPublicKeyInfo structure as specified in RFC 3280. The B<PEM> form is the default format: it consists of the B<DER> format base64 encoded with additional header and footer lines. In the case of a private key PKCS#8 format is also accepted. diff --git a/crypto/openssl/doc/apps/ecparam.pod b/crypto/openssl/doc/apps/ecparam.pod index 788c074d7b45..88e9d1e83d02 100644 --- a/crypto/openssl/doc/apps/ecparam.pod +++ b/crypto/openssl/doc/apps/ecparam.pod @@ -16,7 +16,7 @@ B<openssl ecparam> [B<-C>] [B<-check>] [B<-name arg>] -[B<-list_curve>] +[B<-list_curves>] [B<-conv_form arg>] [B<-param_enc arg>] [B<-no_seed>] diff --git a/crypto/openssl/doc/apps/enc.pod b/crypto/openssl/doc/apps/enc.pod index 3dee4ed99238..41791ad6713c 100644 --- a/crypto/openssl/doc/apps/enc.pod +++ b/crypto/openssl/doc/apps/enc.pod @@ -215,6 +215,10 @@ unsupported options (for example B<openssl enc -help>) includes a list of ciphers, supported by your versesion of OpenSSL, including ones provided by configured engines. +The B<enc> program does not support authenticated encryption modes +like CCM and GCM. The utility does not store or retrieve the +authentication tag. + base64 Base 64 diff --git a/crypto/openssl/doc/apps/gendsa.pod b/crypto/openssl/doc/apps/gendsa.pod index 8c7f114ca08a..d9f56be890f8 100644 --- a/crypto/openssl/doc/apps/gendsa.pod +++ b/crypto/openssl/doc/apps/gendsa.pod @@ -8,6 +8,12 @@ gendsa - generate a DSA private key from a set of parameters B<openssl> B<gendsa> [B<-out filename>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] [B<-des>] [B<-des3>] [B<-idea>] @@ -24,10 +30,10 @@ The B<gendsa> command generates a DSA private key from a DSA parameter file =over 4 -=item B<-des|-des3|-idea> +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +These options encrypt the private key with specified +cipher before outputting it. A pass phrase is prompted for. If none of these options is specified no encryption is used. =item B<-rand file(s)> diff --git a/crypto/openssl/doc/apps/genrsa.pod b/crypto/openssl/doc/apps/genrsa.pod index 7dcac2a779f8..cb03d09b95eb 100644 --- a/crypto/openssl/doc/apps/genrsa.pod +++ b/crypto/openssl/doc/apps/genrsa.pod @@ -9,6 +9,18 @@ genrsa - generate an RSA private key B<openssl> B<genrsa> [B<-out filename>] [B<-passout arg>] +[B<-aes128>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] [B<-des>] [B<-des3>] [B<-idea>] @@ -36,10 +48,10 @@ used. 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)>. -=item B<-des|-des3|-idea> +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. If none of these options is +These options encrypt the private key with specified +cipher before outputting it. If none of these options is specified no encryption is used. If encryption is used a pass phrase is prompted for if it is not supplied via the B<-passout> argument. diff --git a/crypto/openssl/doc/apps/ocsp.pod b/crypto/openssl/doc/apps/ocsp.pod index af2e12e418bf..38f026afc1b6 100644 --- a/crypto/openssl/doc/apps/ocsp.pod +++ b/crypto/openssl/doc/apps/ocsp.pod @@ -133,6 +133,10 @@ if the B<host> option is present then the OCSP request is sent to the host B<hostname> on port B<port>. B<path> specifies the HTTP path name to use or "/" by default. +=item B<-timeout seconds> + +connection timeout to the OCSP responder in seconds + =item B<-CAfile file>, B<-CApath pathname> file or pathname containing trusted CA certificates. These are used to verify diff --git a/crypto/openssl/doc/apps/pkcs12.pod b/crypto/openssl/doc/apps/pkcs12.pod index f69a5c5a4cda..8e0d91798ac4 100644 --- a/crypto/openssl/doc/apps/pkcs12.pod +++ b/crypto/openssl/doc/apps/pkcs12.pod @@ -67,7 +67,7 @@ by default. The filename to write certificates and private keys to, standard output by default. They are all written in PEM format. -=item B<-pass arg>, B<-passin arg> +=item B<-passin arg> the PKCS#12 file (i.e. input file) password source. For more information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in @@ -75,10 +75,15 @@ L<openssl(1)|openssl(1)>. =item B<-passout arg> -pass phrase source to encrypt any outputed private keys with. For more +pass phrase source to encrypt any outputted private keys with. For more information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. +=item B<-password arg> + +With -export, -password is equivalent to -passout. +Otherwise, -password is equivalent to -passin. + =item B<-noout> this option inhibits output of the keys and certificates to the output file diff --git a/crypto/openssl/doc/apps/req.pod b/crypto/openssl/doc/apps/req.pod index ff48bbdf2855..0730d117b39c 100644 --- a/crypto/openssl/doc/apps/req.pod +++ b/crypto/openssl/doc/apps/req.pod @@ -303,7 +303,7 @@ Reverses effect of B<-asn1-kludge> =item B<-newhdr> -Adds the word B<NEW> to the PEM file header and footer lines on the outputed +Adds the word B<NEW> to the PEM file header and footer lines on the outputted request. Some software (Netscape certificate server) and some CAs need this. =item B<-batch> diff --git a/crypto/openssl/doc/apps/rsa.pod b/crypto/openssl/doc/apps/rsa.pod index 69b2bef82cbe..21cbf8ee009b 100644 --- a/crypto/openssl/doc/apps/rsa.pod +++ b/crypto/openssl/doc/apps/rsa.pod @@ -15,6 +15,12 @@ B<openssl> B<rsa> [B<-out filename>] [B<-passout arg>] [B<-sgckey>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] [B<-des>] [B<-des3>] [B<-idea>] @@ -24,6 +30,8 @@ B<openssl> B<rsa> [B<-check>] [B<-pubin>] [B<-pubout>] +[B<-RSAPublicKey_in>] +[B<-RSAPublicKey_out>] [B<-engine id>] =head1 DESCRIPTION @@ -80,10 +88,10 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. use the modified NET algorithm used with some versions of Microsoft IIS and SGC keys. -=item B<-des|-des3|-idea> +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> -These options encrypt the private key with the DES, triple DES, or the -IDEA ciphers respectively before outputting it. A pass phrase is prompted for. +These options encrypt the private key with the specified +cipher before outputting it. A pass phrase is prompted for. If none of these options is specified the key is written in plain text. This means that using the B<rsa> utility to read in an encrypted key with no encryption option can be used to remove the pass phrase from a key, or by @@ -118,6 +126,10 @@ by default a private key is output: with this option a public key will be output instead. This option is automatically set if the input is a public key. +=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out> + +like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead. + =item B<-engine id> specifying an engine (by its unique B<id> string) will cause B<rsa> @@ -139,6 +151,11 @@ The PEM public key format uses the header and footer lines: -----BEGIN PUBLIC KEY----- -----END PUBLIC KEY----- +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. @@ -173,6 +190,10 @@ To just output the public part of a private key: openssl rsa -in key.pem -pubout -out pubkey.pem +Output the public part of a private key in B<RSAPublicKey> format: + + openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem + =head1 BUGS The command line password arguments don't currently work with diff --git a/crypto/openssl/doc/apps/s_client.pod b/crypto/openssl/doc/apps/s_client.pod index 4ebf7b585474..b021c730c02a 100644 --- a/crypto/openssl/doc/apps/s_client.pod +++ b/crypto/openssl/doc/apps/s_client.pod @@ -9,7 +9,9 @@ s_client - SSL/TLS client program B<openssl> B<s_client> [B<-connect host:port>] +[B<-servername name>] [B<-verify depth>] +[B<-verify_return_error>] [B<-cert filename>] [B<-certform DER|PEM>] [B<-key filename>] @@ -27,6 +29,7 @@ B<openssl> B<s_client> [B<-nbio>] [B<-crlf>] [B<-ign_eof>] +[B<-no_ign_eof>] [B<-quiet>] [B<-ssl2>] [B<-ssl3>] @@ -36,6 +39,7 @@ B<openssl> B<s_client> [B<-no_tls1>] [B<-bugs>] [B<-cipher cipherlist>] +[B<-serverpref>] [B<-starttls protocol>] [B<-engine id>] [B<-tlsextdebug>] @@ -43,6 +47,8 @@ B<openssl> B<s_client> [B<-sess_out filename>] [B<-sess_in filename>] [B<-rand file(s)>] +[B<-status>] +[B<-nextprotoneg protocols>] =head1 DESCRIPTION @@ -59,6 +65,10 @@ SSL servers. This specifies the host and optional port to connect to. If not specified then an attempt is made to connect to the local host on port 4433. +=item B<-servername name> + +Set the TLS SNI (Server Name Indication) extension in the ClientHello message. + =item B<-cert certname> The certificate to use, if one is requested by the server. The default is @@ -90,6 +100,11 @@ Currently the verify operation continues after errors so all the problems with a certificate chain can be seen. As a side effect the connection will never fail due to a server certificate verify failure. +=item B<-verify_return_error> + +Return verification errors instead of continuing. This will typically +abort the handshake with a fatal error. + =item B<-CApath directory> The directory to use for server certificate verification. This directory @@ -166,6 +181,11 @@ input. inhibit printing of session and certificate information. This implicitly turns on B<-ign_eof> as well. +=item B<-no_ign_eof> + +shut down the connection when end of file is reached in the input. +Can be used to override the implicit B<-ign_eof> after B<-quiet>. + =item B<-psk_identity identity> Use the PSK identity B<identity> when using a PSK cipher suite. @@ -199,6 +219,10 @@ the server determines which cipher suite is used it should take the first supported cipher in the list sent by the client. See the B<ciphers> command for more information. +=item B<-serverpref> + +use the server's cipher preferences; only used for SSLV2. + =item B<-starttls protocol> send the protocol-specific message(s) to switch to TLS for communication. @@ -237,6 +261,22 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-status> + +sends a certificate status request to the server (OCSP stapling). The server +response (if any) is printed out. + +=item B<-nextprotoneg protocols> + +enable Next Protocol Negotiation TLS extension and provide a list of +comma-separated protocol names that the client should advertise +support for. The list should contain most wanted protocols first. +Protocol names are printable ASCII strings, for example "http/1.1" or +"spdy/3". +Empty list of protocols is treated specially and will cause the client to +advertise support for the TLS extension but disconnect just after +reciving ServerHello with a list of server supported protocols. + =back =head1 CONNECTED COMMANDS @@ -286,6 +326,13 @@ 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 B<-no_sslv2> option. +The B<s_client> utility is a test tool and is designed to continue the +handshake after any certificate verification errors. As a result it will +accept any certificate chain (trusted or not) sent by the peer. None test +applications should B<not> do this as it makes them vulnerable to a MITM +attack. This behaviour can be changed by with the B<-verify_return_error> +option: any verify errors are then returned aborting the handshake. + =head1 BUGS Because this program has a lot of options and also because some of @@ -293,9 +340,6 @@ the techniques used are rather old, the C source of s_client is rather hard to read and not a model of how things should be done. A typical SSL client program would be much simpler. -The B<-verify> option should really exit if the server verification -fails. - The B<-prexit> option is a bit of a hack. We should really report information whenever a session is renegotiated. diff --git a/crypto/openssl/doc/apps/s_server.pod b/crypto/openssl/doc/apps/s_server.pod index 3e503e17e107..2105b603b7ba 100644 --- a/crypto/openssl/doc/apps/s_server.pod +++ b/crypto/openssl/doc/apps/s_server.pod @@ -35,6 +35,7 @@ B<openssl> B<s_server> [B<-CAfile filename>] [B<-nocert>] [B<-cipher cipherlist>] +[B<-serverpref>] [B<-quiet>] [B<-no_tmp_rsa>] [B<-ssl2>] @@ -44,6 +45,7 @@ B<openssl> B<s_server> [B<-no_ssl3>] [B<-no_tls1>] [B<-no_dhe>] +[B<-no_ecdhe>] [B<-bugs>] [B<-hack>] [B<-www>] @@ -54,6 +56,11 @@ B<openssl> B<s_server> [B<-no_ticket>] [B<-id_prefix arg>] [B<-rand file(s)>] +[B<-status>] +[B<-status_verbose>] +[B<-status_timeout nsec>] +[B<-status_url url>] +[B<-nextprotoneg protocols>] =head1 DESCRIPTION @@ -111,7 +118,7 @@ by using an appropriate certificate. =item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg> -addtional certificate and private key format and passphrase respectively. +additional certificate and private key format and passphrase respectively. =item B<-nocert> @@ -131,6 +138,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 loaded effectively +disabling the ephemeral ECDH cipher suites. + =item B<-no_tmp_rsa> certain export cipher suites sometimes use a temporary RSA key, this option @@ -144,6 +156,9 @@ the client. With the B<-verify> option a certificate is requested but the client does not have to send one, with the B<-Verify> option the client must supply a certificate or an error occurs. +If the ciphersuite cannot request a client certificate (for example an +anonymous ciphersuite or PSK) this option has no effect. + =item B<-crl_check>, B<-crl_check_all> Check the peer certificate has not been revoked by its CA. @@ -225,6 +240,10 @@ also included in the server list is used. Because the client specifies the preference order, the order of the server cipherlist irrelevant. See the B<ciphers> command for more information. +=item B<-serverpref> + +use the server's cipher preferences, rather than the client's preferences. + =item B<-tlsextdebug> print out a hex dump of any TLS extensions received from the server. @@ -276,6 +295,33 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-status> + +enables certificate status request support (aka OCSP stapling). + +=item B<-status_verbose> + +enables certificate status request support (aka OCSP stapling) and gives +a verbose printout of the OCSP response. + +=item B<-status_timeout nsec> + +sets the timeout for OCSP response to B<nsec> seconds. + +=item B<-status_url url> + +sets a fallback responder URL to use if no responder URL is present in the +server certificate. Without this option an error is returned if the server +certificate does not contain a responder address. + +=item B<-nextprotoneg protocols> + +enable Next Protocol Negotiation TLS extension and provide a +comma-separated list of supported protocol names. +The list should contain most wanted protocols first. +Protocol names are printable ASCII strings, for example "http/1.1" or +"spdy/3". + =back =head1 CONNECTED COMMANDS diff --git a/crypto/openssl/doc/apps/smime.pod b/crypto/openssl/doc/apps/smime.pod index e4e89af847ae..d39a59a90d8c 100644 --- a/crypto/openssl/doc/apps/smime.pod +++ b/crypto/openssl/doc/apps/smime.pod @@ -159,7 +159,7 @@ EVP_get_cipherbyname() function) can also be used preceded by a dash, for example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers supported by your version of OpenSSL. -If not specified 40 bit RC2 is used. Only used with B<-encrypt>. +If not specified triple DES is used. Only used with B<-encrypt>. =item B<-nointern> @@ -308,28 +308,28 @@ remains DER. =over 4 -=item 0 +=item Z<>0 the operation was completely successfully. -=item 1 +=item Z<>1 an error occurred parsing the command options. -=item 2 +=item Z<>2 one of the input files could not be read. -=item 3 +=item Z<>3 an error occurred creating the PKCS#7 file or when reading the MIME message. -=item 4 +=item Z<>4 an error occurred decrypting or verifying the message. -=item 5 +=item Z<>5 the message was verified correctly but an error occurred writing out the signers certificates. diff --git a/crypto/openssl/doc/apps/ts.pod b/crypto/openssl/doc/apps/ts.pod index 7fb6caa96e54..d6aa47d3144d 100644 --- a/crypto/openssl/doc/apps/ts.pod +++ b/crypto/openssl/doc/apps/ts.pod @@ -352,7 +352,7 @@ switch always overrides the settings in the config file. This is the main section and it specifies the name of another section that contains all the options for the B<-reply> command. This default -section can be overriden with the B<-section> command line switch. (Optional) +section can be overridden with the B<-section> command line switch. (Optional) =item B<oid_file> @@ -453,7 +453,7 @@ included. Default is no. (Optional) =head1 ENVIRONMENT VARIABLES B<OPENSSL_CONF> contains the path of the configuration file and can be -overriden by the B<-config> command line option. +overridden by the B<-config> command line option. =head1 EXAMPLES diff --git a/crypto/openssl/doc/apps/tsget.pod b/crypto/openssl/doc/apps/tsget.pod index b05957beea6b..56db985c4bb1 100644 --- a/crypto/openssl/doc/apps/tsget.pod +++ b/crypto/openssl/doc/apps/tsget.pod @@ -124,7 +124,7 @@ The name of an EGD socket to get random data from. (Optional) =item [request]... List of files containing B<RFC 3161> DER-encoded time stamp requests. If no -requests are specifed only one request will be sent to the server and it will be +requests are specified only one request will be sent to the server and it will be read from the standard input. (Optional) =back diff --git a/crypto/openssl/doc/apps/verify.pod b/crypto/openssl/doc/apps/verify.pod index da683004bd27..0c8e4926ccff 100644 --- a/crypto/openssl/doc/apps/verify.pod +++ b/crypto/openssl/doc/apps/verify.pod @@ -25,6 +25,7 @@ B<openssl> B<verify> [B<-untrusted file>] [B<-help>] [B<-issuer_checks>] +[B<-attime timestamp>] [B<-verbose>] [B<->] [certificates] @@ -47,7 +48,6 @@ of the B<x509> utility). Under Unix the B<c_rehash> script will automatically create symbolic links to a directory of certificates. =item B<-CAfile file> - A file of trusted certificates. The file should contain multiple certificates in PEM format concatenated together. @@ -80,6 +80,12 @@ rejected. The presence of rejection messages does not itself imply that anything is wrong; during the normal verification process, several rejections may take place. +=item B<-attime timestamp> + +Perform validation checks using time specified by B<timestamp> and not +current system time. B<timestamp> is the number of seconds since +01.01.1970 (UNIX time). + =item B<-policy arg> Enable policy processing and add B<arg> to the user-initial-policy-set (see @@ -386,7 +392,7 @@ an application specific error. Unused. =head1 BUGS -Although the issuer checks are a considerably improvement over the old technique they still +Although the issuer checks are a considerable improvement over the old technique they still suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that trusted certificates with matching subject name must either appear in a file (as specified by the B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only diff --git a/crypto/openssl/doc/apps/version.pod b/crypto/openssl/doc/apps/version.pod index e00324c446cd..58f543bc3e64 100644 --- a/crypto/openssl/doc/apps/version.pod +++ b/crypto/openssl/doc/apps/version.pod @@ -13,6 +13,7 @@ B<openssl version> [B<-o>] [B<-f>] [B<-p>] +[B<-d>] =head1 DESCRIPTION @@ -38,7 +39,7 @@ the date the current version of OpenSSL was built. option information: various options set when the library was built. -=item B<-c> +=item B<-f> compilation flags. diff --git a/crypto/openssl/doc/apps/x509.pod b/crypto/openssl/doc/apps/x509.pod index b3c3fcc33b65..878a7c3711ea 100644 --- a/crypto/openssl/doc/apps/x509.pod +++ b/crypto/openssl/doc/apps/x509.pod @@ -19,6 +19,7 @@ B<openssl> B<x509> [B<-hash>] [B<-subject_hash>] [B<-issuer_hash>] +[B<-ocspid>] [B<-subject>] [B<-issuer>] [B<-nameopt option>] @@ -28,6 +29,7 @@ B<openssl> B<x509> [B<-enddate>] [B<-purpose>] [B<-dates>] +[B<-checkend num>] [B<-modulus>] [B<-pubkey>] [B<-fingerprint>] @@ -42,6 +44,7 @@ B<openssl> B<x509> [B<-days arg>] [B<-set_serial n>] [B<-signkey filename>] +[B<-passin arg>] [B<-x509toreq>] [B<-req>] [B<-CA filename>] @@ -49,6 +52,7 @@ B<openssl> B<x509> [B<-CAcreateserial>] [B<-CAserial filename>] [B<-text>] +[B<-certopt option>] [B<-C>] [B<-md2|-md5|-sha1|-mdc2>] [B<-clrext>] @@ -159,6 +163,10 @@ name. outputs the "hash" of the certificate issuer name. +=item B<-ocspid> + +outputs the OCSP hash values for the subject name and public key. + =item B<-hash> synonym for "-subject_hash" for backward compatibility reasons. @@ -208,6 +216,11 @@ prints out the expiry date of the certificate, that is the notAfter date. prints out the start and expiry dates of a certificate. +=item B<-checkend arg> + +checks if the certificate expires within the next B<arg> seconds and exits +non-zero if yes it will expire or zero if not. + =item B<-fingerprint> prints out the digest of the DER encoded version of the whole certificate @@ -313,6 +326,11 @@ If the input is a certificate request then a self signed certificate is created using the supplied private key using the subject name in the request. +=item B<-passin arg> + +the key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. + =item B<-clrext> delete any extensions from a certificate. This option is used when a @@ -468,7 +486,7 @@ using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits. Also if this option is off any UTF8Strings will be converted to their character form first. -=item B<no_type> +=item B<ignore_type> this option does not attempt to interpret multibyte characters in any way. That is their content octets are merely dumped as though one octet diff --git a/crypto/openssl/doc/apps/x509v3_config.pod b/crypto/openssl/doc/apps/x509v3_config.pod index 0450067cf1d9..c82cea1da24e 100644 --- a/crypto/openssl/doc/apps/x509v3_config.pod +++ b/crypto/openssl/doc/apps/x509v3_config.pod @@ -174,7 +174,7 @@ The IP address used in the B<IP> options can be in either IPv4 or IPv6 format. The value of B<dirName> should point to a section containing the distinguished name to use as a set of name value pairs. Multi values AVAs can be formed by -preceeding the name with a B<+> character. +prefacing the name with a B<+> character. otherName can include arbitrary data associated with an OID: the value should be the OID followed by a semicolon and the content in standard @@ -301,7 +301,7 @@ Example: O=Organisation CN=Some Name - + =head2 Certificate Policies. This is a I<raw> extension. All the fields of this extension can be set by @@ -390,7 +390,7 @@ Examples: nameConstraints=permitted;email:.somedomain.com nameConstraints=excluded;email:.com -issuingDistributionPoint = idp_section + =head2 OCSP No Check diff --git a/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod b/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod index 542fd1579ab8..bfa0a04ff974 100644 --- a/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod +++ b/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod @@ -61,7 +61,7 @@ Encode the B<NULL> type, the B<value> string must not be present. =item B<INTEGER>, B<INT> Encodes an ASN1 B<INTEGER> type. The B<value> string represents -the value of the integer, it can be preceeded by a minus sign and +the value of the integer, it can be prefaced by a minus sign and is normally interpreted as a decimal value unless the prefix B<0x> is included. diff --git a/crypto/openssl/doc/crypto/BIO_f_base64.pod b/crypto/openssl/doc/crypto/BIO_f_base64.pod index 438af3b6b66c..d1d7bf0bd066 100644 --- a/crypto/openssl/doc/crypto/BIO_f_base64.pod +++ b/crypto/openssl/doc/crypto/BIO_f_base64.pod @@ -46,11 +46,11 @@ to standard output: b64 = BIO_new(BIO_f_base64()); bio = BIO_new_fp(stdout, BIO_NOCLOSE); - bio = BIO_push(b64, bio); - BIO_write(bio, message, strlen(message)); - BIO_flush(bio); + BIO_push(b64, bio); + BIO_write(b64, message, strlen(message)); + BIO_flush(b64); - BIO_free_all(bio); + BIO_free_all(b64); Read Base64 encoded data from standard input and write the decoded data to standard output: @@ -62,11 +62,12 @@ data to standard output: b64 = BIO_new(BIO_f_base64()); bio = BIO_new_fp(stdin, BIO_NOCLOSE); bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); - bio = BIO_push(b64, bio); - while((inlen = BIO_read(bio, inbuf, 512)) > 0) + BIO_push(b64, bio); + while((inlen = BIO_read(b64, inbuf, 512)) > 0) BIO_write(bio_out, inbuf, inlen); - BIO_free_all(bio); + BIO_flush(bio_out); + BIO_free_all(b64); =head1 BUGS diff --git a/crypto/openssl/doc/crypto/BIO_push.pod b/crypto/openssl/doc/crypto/BIO_push.pod index 8af1d3c09751..8a2657cd588c 100644 --- a/crypto/openssl/doc/crypto/BIO_push.pod +++ b/crypto/openssl/doc/crypto/BIO_push.pod @@ -40,7 +40,7 @@ If the call: BIO_push(b64, f); -is made then the new chain will be B<b64-chain>. After making the calls +is made then the new chain will be B<b64-f>. After making the calls BIO_push(md2, b64); BIO_push(md1, md2); diff --git a/crypto/openssl/doc/crypto/BIO_s_accept.pod b/crypto/openssl/doc/crypto/BIO_s_accept.pod index 7b63e4621b66..b80b6ae48836 100644 --- a/crypto/openssl/doc/crypto/BIO_s_accept.pod +++ b/crypto/openssl/doc/crypto/BIO_s_accept.pod @@ -59,8 +59,8 @@ the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> BIO_set_accept_port() uses the string B<name> to set the accept port. The port is represented as a string of the form "host:port", where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax +The host can be can be "*" which is interpreted as meaning +any interface; "port" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table. diff --git a/crypto/openssl/doc/crypto/BN_BLINDING_new.pod b/crypto/openssl/doc/crypto/BN_BLINDING_new.pod index 5f51fdb47065..da06e4446125 100644 --- a/crypto/openssl/doc/crypto/BN_BLINDING_new.pod +++ b/crypto/openssl/doc/crypto/BN_BLINDING_new.pod @@ -48,7 +48,7 @@ necessary parameters are set, by re-creating the blinding parameters. BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>. If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be -returned in B<r> (this is useful if a B<RSA> object is shared amoung +returned in B<r> (this is useful if a B<RSA> object is shared among several threads). BN_BLINDING_invert_ex() multiplies B<n> with the inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as the inverse blinding. diff --git a/crypto/openssl/doc/crypto/CMS_sign_add1_signer.pod b/crypto/openssl/doc/crypto/CMS_add1_signer.pod index bda3ca2adbd1..a055b82695ae 100644 --- a/crypto/openssl/doc/crypto/CMS_sign_add1_signer.pod +++ b/crypto/openssl/doc/crypto/CMS_add1_signer.pod @@ -2,20 +2,20 @@ =head1 NAME - CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. =head1 SYNOPSIS #include <openssl/cms.h> - CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); + CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); int CMS_SignerInfo_sign(CMS_SignerInfo *si); =head1 DESCRIPTION -CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private +CMS_add1_signer() adds a signer with certificate B<signcert> and private key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData structure B<cms>. @@ -36,7 +36,7 @@ are both set. =head1 NOTES -The main purpose of CMS_sign_add1_signer() is to provide finer control +The main purpose of CMS_add1_signer() is to provide finer control over a CMS signed data structure where the simpler CMS_sign() function defaults are not appropriate. For example if multiple signers or non default digest algorithms are needed. New attributes can also be added using the returned @@ -80,13 +80,13 @@ bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded. -CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added, this can be used to set additional attributes before it is finalized. =head1 RETURN VALUES -CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added or NULL if an error occurs. =head1 SEE ALSO @@ -96,6 +96,6 @@ L<CMS_final(3)|CMS_final(3)>, =head1 HISTORY -CMS_sign_add1_signer() was added to OpenSSL 0.9.8 +CMS_add1_signer() was added to OpenSSL 0.9.8 =cut diff --git a/crypto/openssl/doc/crypto/CMS_decrypt.pod b/crypto/openssl/doc/crypto/CMS_decrypt.pod index d857e4f93f6e..3fa9212af32c 100644 --- a/crypto/openssl/doc/crypto/CMS_decrypt.pod +++ b/crypto/openssl/doc/crypto/CMS_decrypt.pod @@ -27,7 +27,21 @@ function or errors about unknown algorithms will occur. Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the CMS -structure. If B<cert> is set to NULL all possible recipients are tried. +structure. + +If B<cert> is set to NULL all possible recipients are tried. This case however +is problematic. To thwart the MMA attack (Bleichenbacher's attack on +PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or +not. If no recipient succeeds then a random symmetric key is used to decrypt +the content: this will typically output garbage and may (but is not guaranteed +to) ultimately return a padding error only. If CMS_decrypt() just returned an +error when all recipient encrypted keys failed to decrypt an attacker could +use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set +then the above behaviour is modified and an error B<is> returned if no +recipient encrypted key can be decrypted B<without> generating a random +content encryption key. Applications should use this flag with +B<extreme caution> especially in automated gateways as it can leave them +open to attack. It is possible to determine the correct recipient key by other means (for example looking them up in a database) and setting them in the CMS structure diff --git a/crypto/openssl/doc/crypto/CONF_modules_free.pod b/crypto/openssl/doc/crypto/CONF_modules_free.pod index 87bc7b783c9e..347020c5fe70 100644 --- a/crypto/openssl/doc/crypto/CONF_modules_free.pod +++ b/crypto/openssl/doc/crypto/CONF_modules_free.pod @@ -37,7 +37,7 @@ None of the functions return a value. =head1 SEE ALSO L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_modules_load_file(3), CONF_modules_load_file(3)> +L<CONF_modules_load_file(3)|CONF_modules_load_file(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/CONF_modules_load_file.pod b/crypto/openssl/doc/crypto/CONF_modules_load_file.pod index 9965d69bf2ec..0c4d926858fb 100644 --- a/crypto/openssl/doc/crypto/CONF_modules_load_file.pod +++ b/crypto/openssl/doc/crypto/CONF_modules_load_file.pod @@ -51,7 +51,7 @@ return value of the failing module (this will always be zero or negative). =head1 SEE ALSO L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)> +L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/ERR_get_error.pod b/crypto/openssl/doc/crypto/ERR_get_error.pod index 34443045fc0d..01e196c95fda 100644 --- a/crypto/openssl/doc/crypto/ERR_get_error.pod +++ b/crypto/openssl/doc/crypto/ERR_get_error.pod @@ -49,11 +49,14 @@ additionally store the file name and line number where the error occurred in *B<file> and *B<line>, unless these are B<NULL>. ERR_get_error_line_data(), ERR_peek_error_line_data() and -ERR_get_last_error_line_data() store additional data and flags +ERR_peek_last_error_line_data() store additional data and flags associated with the error code in *B<data> and *B<flags>, unless these are B<NULL>. *B<data> contains a string -if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(), -*B<flags>&B<ERR_TXT_MALLOCED> is true. +if *B<flags>&B<ERR_TXT_STRING> is true. + +An application B<MUST NOT> free the *B<data> pointer (or any other pointers +returned by these functions) with OPENSSL_free() as freeing is handled +automatically by the error library. =head1 RETURN VALUES diff --git a/crypto/openssl/doc/crypto/EVP_BytesToKey.pod b/crypto/openssl/doc/crypto/EVP_BytesToKey.pod index d375c46e03d5..0ea7d55c0f1f 100644 --- a/crypto/openssl/doc/crypto/EVP_BytesToKey.pod +++ b/crypto/openssl/doc/crypto/EVP_BytesToKey.pod @@ -17,7 +17,7 @@ EVP_BytesToKey - password based encryption routine EVP_BytesToKey() derives a key and IV from various parameters. B<type> is the cipher to derive the key and IV for. B<md> is the message digest to use. -The B<salt> paramter is used as a salt in the derivation: it should point to +The B<salt> parameter is used as a salt in the derivation: it should point to an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing B<datal> bytes which is used to derive the keying data. B<count> is the iteration count to use. The derived key and IV will be written to B<key> diff --git a/crypto/openssl/doc/crypto/EVP_DigestInit.pod b/crypto/openssl/doc/crypto/EVP_DigestInit.pod index 367691cc7aed..ac526bb6dbcb 100644 --- a/crypto/openssl/doc/crypto/EVP_DigestInit.pod +++ b/crypto/openssl/doc/crypto/EVP_DigestInit.pod @@ -26,13 +26,13 @@ EVP digest routines int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); - int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); + int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); - int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); + int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); #define EVP_MAX_MD_SIZE 64 /* SHA512 */ @@ -136,10 +136,10 @@ reasons. EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 -and RIPEMD160 digest algorithms respectively. +and RIPEMD160 digest algorithms respectively. EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. Note: there is +algorithms but using DSS (DSA) for the signature algorithm. Note: there is no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are however retained for compatibility. @@ -161,9 +161,8 @@ EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none exists. -EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), -EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block -size in bytes. +EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and +EVP_MD_CTX_block_size() return the digest or block size in bytes. EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the @@ -178,21 +177,21 @@ The B<EVP> interface to message digests should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the digest used and much more flexible. -New applications should use the SHA2 digest algorithms such as SHA256. +New applications should use the SHA2 digest algorithms such as SHA256. The other digest algorithms are still in common use. For most applications the B<impl> parameter to EVP_DigestInit_ex() will be set to NULL to use the default digest implementation. -The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are +The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are obsolete but are retained to maintain compatibility with existing code. New -applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and +applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context instead of initializing and cleaning it up on each call and allow non default implementations of digests to be specified. In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use -memory leaks will occur. +memory leaks will occur. Stack allocation of EVP_MD_CTX structures is common, for example: @@ -246,15 +245,19 @@ digest name passed on the command line. EVP_MD_CTX_destroy(mdctx); printf("Digest is: "); - for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); + for(i = 0; i < md_len; i++) + printf("%02x", md_value[i]); printf("\n"); + + /* Call this once before exit. */ + EVP_cleanup(); + exit(0); } =head1 SEE ALSO -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<dgst(1)|dgst(1)>, +L<evp(3)|evp(3)> =head1 HISTORY @@ -270,7 +273,7 @@ EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were changed to return truely const EVP_MD * in OpenSSL 0.9.7. The link between digests and signing algorithms was fixed in OpenSSL 1.0 and -later, so now EVP_sha1() can be used with RSA and DSA, there is no need to +later, so now EVP_sha1() can be used with RSA and DSA; there is no need to use EVP_dss1() any more. OpenSSL 1.0 and later does not include the MD2 digest algorithm in the diff --git a/crypto/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/crypto/openssl/doc/crypto/EVP_DigestVerifyInit.pod index f22448897839..cfeccd96effc 100644 --- a/crypto/openssl/doc/crypto/EVP_DigestVerifyInit.pod +++ b/crypto/openssl/doc/crypto/EVP_DigestVerifyInit.pod @@ -38,7 +38,7 @@ or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm. Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only -indicates that the signature did not not verify successfully (that is tbs did +indicates that the signature did not verify successfully (that is tbs did not match the original data or the signature was of invalid form) it is not an indication of a more serious error. @@ -59,7 +59,7 @@ For some key types and parameters the random number generator must be seeded or the operation will fail. The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest -context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can +context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data. Since only a copy of the digest context is ever finalized the context must diff --git a/crypto/openssl/doc/crypto/EVP_EncryptInit.pod b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod index 8271d3dfc417..ed027b387aea 100644 --- a/crypto/openssl/doc/crypto/EVP_EncryptInit.pod +++ b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod @@ -115,7 +115,7 @@ writes the encrypted version to B<out>. This function can be called multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the encrypted data: as a result the amount of data written may be anything from zero bytes -to (inl + cipher_block_size - 1) so B<outl> should contain sufficient +to (inl + cipher_block_size - 1) so B<out> should contain sufficient room. The actual number of bytes written is placed in B<outl>. If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts @@ -152,7 +152,7 @@ does not remain in memory. EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and -EVP_CipherInit_ex() except the B<ctx> paramter does not need to be +EVP_CipherInit_ex() except the B<ctx> parameter does not need to be initialized and they always use the default cipher implementation. EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a @@ -344,7 +344,10 @@ bits and 12 rounds. Where possible the B<EVP> interface to symmetric ciphers should be used in preference to the low level interfaces. This is because the code then becomes -transparent to the cipher used and much more flexible. +transparent to the cipher used and much more flexible. Additionally, the +B<EVP> interface will ensure the use of platform specific cryptographic +acceleration such as AES-NI (the low level interfaces do not provide the +guarantee). PKCS padding works by adding B<n> padding bytes of value B<n> to make the total length of the encrypted data a multiple of the block size. Padding is always @@ -384,27 +387,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. =head1 EXAMPLES -Get the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); - -Get the RC2 effective key length: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); - -Set the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); - -Set the effective key length used in RC2: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); - -Encrypt a string using blowfish: +Encrypt a string using IDEA: int do_crypt(char *outfile) { @@ -418,8 +401,9 @@ Encrypt a string using blowfish: char intext[] = "Some Crypto Text"; EVP_CIPHER_CTX ctx; FILE *out; + EVP_CIPHER_CTX_init(&ctx); - EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); + EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv); if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) { @@ -448,28 +432,34 @@ Encrypt a string using blowfish: } The ciphertext from the above example can be decrypted using the B<openssl> -utility with the command line: +utility with the command line (shown on two lines for clarity): - S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> + openssl idea -d <filename + -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -General encryption, decryption function example using FILE I/O and RC2 with an -80 bit key: +General encryption and decryption function example using FILE I/O and AES128 +with a 128-bit key: int do_crypt(FILE *in, FILE *out, int do_encrypt) { /* Allow enough space in output buffer for additional block */ - inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; + unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; int inlen, outlen; + EVP_CIPHER_CTX ctx; /* Bogus key and IV: we'd normally set these from * another source. */ - unsigned char key[] = "0123456789"; - unsigned char iv[] = "12345678"; - /* Don't set key or IV because we will modify the parameters */ + unsigned char key[] = "0123456789abcdeF"; + unsigned char iv[] = "1234567887654321"; + + /* Don't set key or IV right away; we want to check lengths */ EVP_CIPHER_CTX_init(&ctx); - EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); - EVP_CIPHER_CTX_set_key_length(&ctx, 10); - /* We finished modifying parameters so now we can set key and IV */ + EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, + do_encrypt); + OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16); + OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16); + + /* Now we can set key and IV */ EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); for(;;) @@ -508,4 +498,7 @@ EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in OpenSSL 0.9.7. +IDEA appeared in OpenSSL 0.9.7 but was often disabled due to +patent concerns; the last patents expired in 2012. + =cut diff --git a/crypto/openssl/doc/crypto/EVP_PKEY_encrypt.pod b/crypto/openssl/doc/crypto/EVP_PKEY_encrypt.pod index e495a81242b9..6799ce1010bd 100644 --- a/crypto/openssl/doc/crypto/EVP_PKEY_encrypt.pod +++ b/crypto/openssl/doc/crypto/EVP_PKEY_encrypt.pod @@ -43,19 +43,23 @@ indicates the operation is not supported by the public key algorithm. =head1 EXAMPLE -Encrypt data using OAEP (for RSA keys): +Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)|pem(3)> or +L<d2i_X509(3)|d2i_X509(3)> for means to load a public key. You may also simply +set 'eng = NULL;' to start with the default OpenSSL RSA implementation: #include <openssl/evp.h> #include <openssl/rsa.h> + #include <openssl/engine.h> EVP_PKEY_CTX *ctx; + ENGINE *eng; unsigned char *out, *in; size_t outlen, inlen; EVP_PKEY *key; - /* NB: assumes key in, inlen are already set up + /* NB: assumes eng, key, in, inlen are already set up, * and that key is an RSA public key */ - ctx = EVP_PKEY_CTX_new(key); + ctx = EVP_PKEY_CTX_new(key,eng); if (!ctx) /* Error occurred */ if (EVP_PKEY_encrypt_init(ctx) <= 0) @@ -79,6 +83,8 @@ Encrypt data using OAEP (for RSA keys): =head1 SEE ALSO +L<d2i_X509(3)|d2i_X509(3)>, +L<engine(3)|engine(3)>, L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, diff --git a/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod index 2db692e2719e..6f1017561516 100644 --- a/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod +++ b/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -37,7 +37,7 @@ 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_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +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> however these use the supplied B<key> internally and so B<key> will be freed when the parent B<pkey> is freed. @@ -54,8 +54,8 @@ 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() -EVP_PKEY_assign_EC_KEY() are implemented as macros. +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +and EVP_PKEY_assign_EC_KEY() are implemented as macros. =head1 RETURN VALUES @@ -66,7 +66,7 @@ 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() +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. =head1 SEE ALSO diff --git a/crypto/openssl/doc/crypto/EVP_PKEY_sign.pod b/crypto/openssl/doc/crypto/EVP_PKEY_sign.pod index a044f2c13127..21974b4b1a9c 100644 --- a/crypto/openssl/doc/crypto/EVP_PKEY_sign.pod +++ b/crypto/openssl/doc/crypto/EVP_PKEY_sign.pod @@ -28,9 +28,14 @@ B<sig> and the amount of data written to B<siglen>. =head1 NOTES +EVP_PKEY_sign() does not hash the data to be signed, and therefore is +normally used to sign digests. For signing arbitrary messages, see the +L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and +L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead. + After the call to EVP_PKEY_sign_init() algorithm specific control operations can be performed to set any appropriate parameters for the -operation. +operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>). The function EVP_PKEY_sign() can be called more than once on the same context if several operations are performed using the same parameters. @@ -49,13 +54,17 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest: #include <openssl/rsa.h> EVP_PKEY_CTX *ctx; + /* md is a SHA-256 digest in this example. */ unsigned char *md, *sig; - size_t mdlen, siglen; + size_t mdlen = 32, siglen; EVP_PKEY *signing_key; - /* NB: assumes signing_key, md and mdlen are already set up - * and that signing_key is an RSA private key + + /* + * NB: assumes signing_key and md are set up before the next + * step. signing_key must be an RSA private key and md must + * point to the SHA-256 digest to be signed. */ - ctx = EVP_PKEY_CTX_new(signing_key); + ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); if (!ctx) /* Error occurred */ if (EVP_PKEY_sign_init(ctx) <= 0) @@ -83,6 +92,7 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest: =head1 SEE ALSO L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>, L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, diff --git a/crypto/openssl/doc/crypto/EVP_SignInit.pod b/crypto/openssl/doc/crypto/EVP_SignInit.pod index 620a623ab620..14ecc775af6a 100644 --- a/crypto/openssl/doc/crypto/EVP_SignInit.pod +++ b/crypto/openssl/doc/crypto/EVP_SignInit.pod @@ -30,9 +30,11 @@ signature context B<ctx>. This function can be called several times on the same B<ctx> to include additional data. EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and -places the signature in B<sig>. The number of bytes of data written (i.e. the -length of the signature) will be written to the integer at B<s>, at most -EVP_PKEY_size(pkey) bytes will be written. +places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey) +bytes in size. B<s> is an OUT paramter, and not used as an IN parameter. +The number of bytes of data written (i.e. the length of the signature) +will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes +will be written. EVP_SignInit() initializes a signing context B<ctx> to use the default implementation of digest B<type>. diff --git a/crypto/openssl/doc/crypto/OPENSSL_config.pod b/crypto/openssl/doc/crypto/OPENSSL_config.pod index e7bba2aacae0..888de88f6bbf 100644 --- a/crypto/openssl/doc/crypto/OPENSSL_config.pod +++ b/crypto/openssl/doc/crypto/OPENSSL_config.pod @@ -73,7 +73,7 @@ Neither OPENSSL_config() nor OPENSSL_no_config() return a value. =head1 SEE ALSO L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>, -L<CONF_modules_free(3),CONF_modules_free(3)> +L<CONF_modules_free(3)|CONF_modules_free(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/RSA_set_method.pod b/crypto/openssl/doc/crypto/RSA_set_method.pod index 2c963d7e5bba..0ef078118651 100644 --- a/crypto/openssl/doc/crypto/RSA_set_method.pod +++ b/crypto/openssl/doc/crypto/RSA_set_method.pod @@ -125,14 +125,18 @@ the default method is used. /* sign. For backward compatibility, this is used only * if (flags & RSA_FLAG_SIGN_VER) */ - int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - + int (*rsa_sign)(int type, + const unsigned char *m, unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, const RSA *rsa); /* verify. For backward compatibility, this is used only * if (flags & RSA_FLAG_SIGN_VER) */ - int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + int (*rsa_verify)(int dtype, + const unsigned char *m, unsigned int m_length, + const unsigned char *sigbuf, unsigned int siglen, + const RSA *rsa); + /* keygen. If NULL builtin RSA key generation will be used */ + int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); } RSA_METHOD; diff --git a/crypto/openssl/doc/crypto/RSA_sign.pod b/crypto/openssl/doc/crypto/RSA_sign.pod index 8553be8e99b6..fc16b1f4f806 100644 --- a/crypto/openssl/doc/crypto/RSA_sign.pod +++ b/crypto/openssl/doc/crypto/RSA_sign.pod @@ -20,6 +20,10 @@ RSA_sign() signs the message digest B<m> of size B<m_len> using the private key B<rsa> as specified in PKCS #1 v2.0. It stores the signature in B<sigret> and the signature size in B<siglen>. B<sigret> must point to RSA_size(B<rsa>) bytes of memory. +Note that PKCS #1 adds meta-data, placing limits on the size of the +key that can be used. +See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level +operations. B<type> denotes the message digest algorithm that was used to generate B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; diff --git a/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod index 41902c0d4553..4716e7ee7542 100644 --- a/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ b/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod @@ -65,7 +65,7 @@ set first so the relevant field information can be looked up internally. =head1 SEE ALSO L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<OBJ_nid2obj(3),OBJ_nid2obj(3)> +L<OBJ_nid2obj(3)|OBJ_nid2obj(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod index 1afd008cb372..043766cc461b 100644 --- a/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ b/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod @@ -81,14 +81,14 @@ Create an B<X509_NAME> structure: nm = X509_NAME_new(); if (nm == NULL) /* Some error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "C", "UK", -1, -1, 0)) + if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, + "UK", -1, -1, 0)) /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "O", "Disorganized Organization", -1, -1, 0)) + if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, + "Disorganized Organization", -1, -1, 0)) /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "CN", "Joe Bloggs", -1, -1, 0)) + if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, + "Joe Bloggs", -1, -1, 0)) /* Error */ =head1 RETURN VALUES diff --git a/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod index 3b1f9ff43b65..c8a812879561 100644 --- a/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod +++ b/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod @@ -59,6 +59,10 @@ X509_NAME_get_index_by_OBJ() should be used followed by X509_NAME_get_entry() on any matching indices and then the various B<X509_NAME_ENTRY> utility functions on the result. +The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in +the source code header files E<lt>openssl/obj_mac.hE<gt> and/or +E<lt>openssl/objects.hE<gt>. + =head1 EXAMPLES Process all entries: diff --git a/crypto/openssl/doc/crypto/X509_STORE_CTX_get_error.pod b/crypto/openssl/doc/crypto/X509_STORE_CTX_get_error.pod index a883f6c09783..60e8332ae9dd 100644 --- a/crypto/openssl/doc/crypto/X509_STORE_CTX_get_error.pod +++ b/crypto/openssl/doc/crypto/X509_STORE_CTX_get_error.pod @@ -278,6 +278,8 @@ happen if extended CRL checking is enabled. an application specific error. This will never be returned unless explicitly set by an application. +=back + =head1 NOTES The above functions should be used instead of directly referencing the fields diff --git a/crypto/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/crypto/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod index 8d6b9dda47e7..8a9243d75613 100644 --- a/crypto/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod +++ b/crypto/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod @@ -15,7 +15,7 @@ X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); - char *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); + void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/crypto/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod index b68eece03387..46cac2bea2be 100644 --- a/crypto/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ b/crypto/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -113,7 +113,7 @@ a special status code is set to the verification callback. This permits it to examine the valid policy tree and perform additional checks or simply log it for debugging purposes. -By default some addtional features such as indirect CRLs and CRLs signed by +By default some additional features such as indirect CRLs and CRLs signed by different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set they are enabled. diff --git a/crypto/openssl/doc/crypto/des.pod b/crypto/openssl/doc/crypto/des.pod index 6f0cf1cc5e5f..e1add56b5e81 100644 --- a/crypto/openssl/doc/crypto/des.pod +++ b/crypto/openssl/doc/crypto/des.pod @@ -135,9 +135,8 @@ depend on a global variable. DES_set_odd_parity() sets the parity of the passed I<key> to odd. -DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it -is ok. The probability that a randomly generated key is weak is -1/2^52, so it is not really worth checking for them. +DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it +is ok. The following routines mostly operate on an input and output stream of I<DES_cblock>s. @@ -181,7 +180,7 @@ 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 -really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. +an 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)))>. diff --git a/crypto/openssl/doc/crypto/ecdsa.pod b/crypto/openssl/doc/crypto/ecdsa.pod index 20edff97ffd6..59a5916de123 100644 --- a/crypto/openssl/doc/crypto/ecdsa.pod +++ b/crypto/openssl/doc/crypto/ecdsa.pod @@ -95,7 +95,7 @@ is ignored. ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a valid ECDSA signature of the hash value -value B<dgst> of size B<dgstlen> using the public key B<eckey>. +B<dgst> of size B<dgstlen> using the public key B<eckey>. The parameter B<type> is ignored. ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> @@ -131,16 +131,12 @@ specific) int ret; ECDSA_SIG *sig; - EC_KEY *eckey = EC_KEY_new(); + EC_KEY *eckey; + eckey = EC_KEY_new_by_curve_name(NID_secp192k1); if (eckey == NULL) { /* error */ } - key->group = EC_GROUP_new_by_nid(NID_secp192k1); - if (key->group == NULL) - { - /* error */ - } if (!EC_KEY_generate_key(eckey)) { /* error */ diff --git a/crypto/openssl/doc/crypto/err.pod b/crypto/openssl/doc/crypto/err.pod index 6f729554d2a9..4a5dc6935cc7 100644 --- a/crypto/openssl/doc/crypto/err.pod +++ b/crypto/openssl/doc/crypto/err.pod @@ -171,7 +171,6 @@ ERR_get_string_table(void) respectively. =head1 SEE ALSO -L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>, L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, diff --git a/crypto/openssl/doc/crypto/pem.pod b/crypto/openssl/doc/crypto/pem.pod index d5b189611956..21e9fe3b98a9 100644 --- a/crypto/openssl/doc/crypto/pem.pod +++ b/crypto/openssl/doc/crypto/pem.pod @@ -201,7 +201,7 @@ handle PKCS#8 format encrypted and unencrypted keys too. PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption -algorithms. The B<cipher> argument specifies the encryption algoritm to +algorithms. The B<cipher> argument specifies the encryption algorithm to use: unlike all other PEM routines the encryption is applied at the PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. @@ -450,9 +450,9 @@ byte B<salt> encoded as a set of hexadecimal digits. After this is the base64 encoded encrypted data. -The encryption key is determined using EVP_bytestokey(), using B<salt> and an +The encryption key is determined using EVP_BytesToKey(), using B<salt> and an iteration count of 1. The IV used is the value of B<salt> and *not* the IV -returned by EVP_bytestokey(). +returned by EVP_BytesToKey(). =head1 BUGS @@ -474,3 +474,7 @@ The read routines return either a pointer to the structure read or NULL if an error occurred. The write routines return 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> diff --git a/crypto/openssl/doc/crypto/ui.pod b/crypto/openssl/doc/crypto/ui.pod index 6df68d604a82..04f8e9c360a8 100644 --- a/crypto/openssl/doc/crypto/ui.pod +++ b/crypto/openssl/doc/crypto/ui.pod @@ -119,7 +119,7 @@ verification will fail. UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered in a boolean way, with a single character for yes and a different character for no. A set of characters that can be used to cancel the prompt is given -as well. The prompt itself is really divided in two, one part being the +as well. The prompt itself is divided in two, one part being the descriptive text (given through the I<prompt> argument) and one describing the possible answers (given through the I<action_desc> argument). diff --git a/crypto/openssl/doc/fingerprints.txt b/crypto/openssl/doc/fingerprints.txt index 7d05a855946b..373e90d0a1e7 100644 --- a/crypto/openssl/doc/fingerprints.txt +++ b/crypto/openssl/doc/fingerprints.txt @@ -4,12 +4,11 @@ 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 0.9.7f, openssl-0.9.7f.tar.gz, is found in -the file openssl-0.9.7f.tar.gz.asc. +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. The following is the list of fingerprints for the keys that are -currently in use (have been used since summer 2004) to sign OpenSSL -distributions: +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 @@ -21,16 +20,19 @@ 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/26BB437D 1997-04-28 - Key fingerprint = 00 C9 21 8E D1 AB 70 37 DD 67 A2 3A 0A 6F 8D A5 -uid Ralf S. Engelschall <rse@engelschall.com> - 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 @@ -55,3 +57,7 @@ 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> +pub 2048R/0E604491 2013-04-30 + Key fingerprint = 8657 ABB2 60F0 56B1 E519 0839 D9C4 D26D 0E60 4491 +uid Matt Caswell <frodo@baggins.org> + diff --git a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod index eb772b55de4a..2e113be6065c 100644 --- a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod +++ b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod @@ -23,8 +23,12 @@ SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If B<alg_bits> is not NULL, it contains the number of bits processed by the chosen algorithm. If B<cipher> is NULL, 0 is returned. -SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently -"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned. +SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol +version that first defined the cipher. +This is currently B<SSLv2> or B<TLSv1/SSLv3>. +In some cases it should possibly return "TLSv1.2" but does not; +use SSL_CIPHER_description() instead. +If B<cipher> is NULL, "(NONE)" is returned. SSL_CIPHER_description() returns a textual description of the cipher used into the buffer B<buf> of length B<len> provided. B<len> must be at least @@ -52,7 +56,8 @@ Textual representation of the cipher name. =item <protocol version> -Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3. +Protocol version: B<SSLv2>, B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are +flagged with SSLv3. No new ciphers were added by TLSv1.1. =item Kx=<key exchange> @@ -91,6 +96,10 @@ Some examples for the output of SSL_CIPHER_description(): RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +A comp[lete list can be retrieved by invoking the following command: + + openssl ciphers -v ALL + =head1 BUGS If SSL_CIPHER_description() is called with B<cipher> being NULL, the diff --git a/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod b/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod index 42fa66b19751..f4d191c9b6bd 100644 --- a/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod +++ b/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod @@ -53,11 +53,11 @@ SSL_COMP_add_compression_method() may return the following values: =over 4 -=item 0 +=item Z<>0 The operation succeeded. -=item 1 +=item Z<>1 The operation failed. Check the error queue to find out the reason. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod index ee28f5ccc3a3..5955ee1cb415 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -24,6 +24,16 @@ the library will try to complete the chain from the available CA certificates in the trusted CA storage, see L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. +The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be freed by the library when the B<SSL_CTX> is destroyed. An application B<should not> free the B<x509> object. + +=head1 RESTRICTIONS + +Only one set of extra chain certificates can be specified per SSL_CTX +structure. Different chains for different certificates (for example if both +RSA and DSA certificates are specified by the same server) or different SSL +structures with the same parent SSL_CTX cannot be specified using this +function. + =head1 RETURN VALUES SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the diff --git a/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod index 82676b26b239..c660a18fc2a1 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod @@ -41,7 +41,7 @@ If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE flag then the internal cache will not be populated automatically by new sessions negotiated by the SSL/TLS implementation, even though the internal cache will be searched automatically for session-resume requests (the -latter can be surpressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the +latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the application can use SSL_CTX_add_session() directly to have full control over the sessions that can be resumed if desired. @@ -52,13 +52,13 @@ The following values are returned by all functions: =over 4 -=item 0 +=item Z<>0 The operation failed. In case of the add operation, it was tried to add the same (identical) session twice. In case of the remove operation, the session was not found in the cache. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod index 84a799fc71dd..d1d897719531 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -100,13 +100,13 @@ The following return values can occur: =over 4 -=item 0 +=item Z<>0 The operation failed because B<CAfile> and B<CApath> are NULL or the processing at one of the locations specified failed. Check the error stack to find out the reason. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_new.pod b/crypto/openssl/doc/ssl/SSL_CTX_new.pod index 73e8c47f9a2e..491ac8c172cb 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_new.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_new.pod @@ -51,22 +51,36 @@ SSLv3 client hello messages. =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) -A TLS/SSL connection established with these methods will understand the SSLv2, -SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages -and will indicate that it also understands SSLv3 and TLSv1. A server will -understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best -choice when compatibility is a concern. +A TLS/SSL connection established with these methods may understand the SSLv2, +SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. + +If the cipher list does not contain any SSLv2 ciphersuites (the default +cipher list does not) or extensions are required (for example server name) +a client will send out TLSv1 client hello messages including extensions and +will indicate that it also understands TLSv1.1, TLSv1.2 and permits a +fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 +protocols. This is the best choice when compatibility is a concern. + +If any SSLv2 ciphersuites are included in the cipher list and no extensions +are required then SSLv2 compatible client hellos will be used by clients and +SSLv2 will be accepted by servers. This is B<not> recommended due to the +insecurity of SSLv2 and the limited nature of the SSLv2 client hello +prohibiting the use of extensions. =back The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or -B<SSL_set_options()> functions. Using these options it is possible to choose -e.g. SSLv23_server_method() and be able to negotiate with all possible -clients, but to only allow newer protocols like SSLv3 or TLSv1. +SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 +options of the SSL_CTX_set_options() or SSL_set_options() functions. +Using these options it is possible to choose e.g. SSLv23_server_method() and +be able to negotiate with all possible clients, but to only allow newer +protocols like TLSv1, TLSv1.1 or TLS v1.2. + +Applications which never want to support SSLv2 (even is the cipher string +is configured to use SSLv2 ciphersuites) can set SSL_OP_NO_SSLv2. SSL_CTX_new() initializes the list of ciphers, the session cache setting, -the callbacks, the keys and certificates, and the options to its default +the callbacks, the keys and certificates and the options to its default values. =head1 RETURN VALUES diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod index ed64f6415702..bd4df4abd461 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -54,6 +54,10 @@ of 512 bits and the server is not configured to use temporary RSA keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated and the handshake will fail. +If the cipher list does not contain any SSLv2 cipher suites (this is the +default) then SSLv2 is effectively disabled and neither clients nor servers +will attempt to use SSLv2. + =head1 RETURN VALUES SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod index 632b556d1262..4965385e97ae 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -35,7 +35,7 @@ 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_options()>), it sends a list of CAs, for which +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 @@ -66,16 +66,16 @@ values: =over 4 -=item 1 - -The operation succeeded. - -=item 0 +=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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod index 3465b5c7bbaf..d0df69a9bc18 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -29,7 +29,7 @@ using the B<x509> and B<pkey> arguments and "1" must be returned. The certificate will be installed into B<ssl>, see the NOTES and BUGS sections. If no certificate should be set, "0" has to be returned and no certificate will be sent. A negative return value will suspend the handshake and the -handshake function will return immediatly. L<SSL_get_error(3)|SSL_get_error(3)> +handshake function will return immediately. L<SSL_get_error(3)|SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was suspended. The next call to the handshake function will again lead to the call of client_cert_cb(). It is the job of the client_cert_cb() to store information diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod index 8cb669daeb78..2a5aaa555e13 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod @@ -71,6 +71,16 @@ SSL_CTX->freelist_max_len, which defaults to 32. Using this flag can save around 34k per idle SSL connection. This flag has no effect on SSL v2 connections, or on DTLS connections. +=item SSL_MODE_SEND_FALLBACK_SCSV + +Send TLS_FALLBACK_SCSV in the ClientHello. +To be set only by applications that reconnect with a downgraded protocol +version; see draft-ietf-tls-downgrade-scsv-00 for details. + +DO NOT ENABLE THIS if your application attempts a normal handshake. +Only use this in explicit fallback retries, following the guidance +in draft-ietf-tls-downgrade-scsv-00. + =back =head1 RETURN VALUES diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod index 0015e6ea7923..8b82d94a389e 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -11,8 +11,8 @@ SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SS void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); - void SSL_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + void SSL_set_msg_callback(SSL *ssl, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + void SSL_set_msg_callback_arg(SSL *ssl, void *arg); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod index c4b9ac20c231..e80a72cd4d06 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -88,9 +88,10 @@ As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. ... -=item SSL_OP_MSIE_SSLV2_RSA_PADDING +=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG -As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. +Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. +OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. =item SSL_OP_SSLEAY_080_CLIENT_DH_BUG @@ -111,6 +112,12 @@ vulnerability affecting CBC ciphers, which cannot be handled by some broken SSL implementations. This option has no effect for connections using other ciphers. +=item SSL_OP_TLSEXT_PADDING + +Adds a padding extension to ensure the ClientHello size is never between +256 and 511 bytes in length. This is needed as a workaround for some +implementations. + =item SSL_OP_ALL All of the above bug workarounds. @@ -241,7 +248,7 @@ Connections and renegotiation are always permitted by OpenSSL implementations. =head2 Unpatched client and patched OpenSSL server -The initial connection suceeds but client renegotiation is denied by the +The initial connection succeeds but client renegotiation is denied by the server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal B<handshake_failure> alert in SSL v3.0. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod index 58fc685506eb..7c9e5153360a 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -64,13 +64,13 @@ return the following values: =over 4 -=item 0 +=item Z<>0 The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error is logged to the error stack. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod index 254f2b4397fa..e254f9657bd5 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -42,11 +42,11 @@ and SSL_set_ssl_method(): =over 4 -=item 0 +=item Z<>0 The new choice failed, check the error stack to find out the reason. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod new file mode 100644 index 000000000000..da0dd0f597e4 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -0,0 +1,195 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing + +=head1 SYNOPSIS + + #include <openssl/tls1.h> + + long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, + int (*cb)(SSL *s, unsigned char key_name[16], + unsigned char iv[EVP_MAX_IV_LENGTH], + EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); + +=head1 DESCRIPTION + +SSL_CTX_set_tlsext_ticket_key_cb() sets a callback fuction I<cb> for handling +session tickets for the ssl context I<sslctx>. Session tickets, defined in +RFC5077 provide an enhanced session resumption capability where the server +implementation is not required to maintain per session state. It only applies +to TLS and there is no SSLv3 implementation. + +The callback is available when the OpenSSL library was built without +I<OPENSSL_NO_TLSEXT> being defined. + +The callback function I<cb> will be called for every client instigated TLS +session when session ticket extension is presented in the TLS hello +message. It is the responsibility of this function to create or retrieve the +cryptographic parameters and to maintain their state. + +The OpenSSL library uses your callback function to help implement a common TLS +ticket construction state according to RFC5077 Section 4 such that per session +state is unnecessary and a small set of cryptographic variables needs to be +maintained by the callback function implementation. + +In order to reuse a session, a TLS client must send the a session ticket +extension to the server. The client can only send exactly one session ticket. +The server, through the callback function, either agrees to reuse the session +ticket information or it starts a full TLS handshake to create a new session +ticket. + +Before the callback function is started I<ctx> and I<hctx> have been +initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively. + +For new sessions tickets, when the client doesn't present a session ticket, or +an attempted retreival of the ticket failed, or a renew option was indicated, +the callback function will be called with I<enc> equal to 1. The OpenSSL +library expects that the function will set an arbitary I<name>, initialize +I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>. + +The I<name> is 16 characters long and is used as a key identifier. + +The I<iv> length is the length of the IV of the corresponding cipher. The +maximum IV length is L<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>. + +The initialization vector I<iv> should be a random value. The cipher context +I<ctx> should use the initialisation vector I<iv>. The cipher context can be +set using L<EVP_EncryptInit_ex>. The hmac context can be set using L<HMAC_Init_ex>. + +When the client presents a session ticket, the callback function with be called +with I<enc> set to 0 indicating that the I<cb> function should retreive a set +of parameters. In this case I<name> and I<iv> have already been parsed out of +the session ticket. The OpenSSL library expects that the I<name> will be used +to retrieve a cryptographic parameters and that the cryptographic context +I<ctx> will be set with the retreived parameters and the initialization vector +I<iv>. using a function like L<EVP_DecryptInit_ex>. The I<hctx> needs to be set +using L<HMAC_Init_ex>. + +If the I<name> is still valid but a renewal of the ticket is required the +callback function should return 2. The library will call the callback again +with an arguement of enc equal to 1 to set the new ticket. + +The return value of the I<cb> function is used by OpenSSL to determine what +further processing will occur. The following return values have meaning: + +=over 4 + +=item Z<>2 + +This indicates that the I<ctx> and I<hctx> have been set and the session can +continue on those parameters. Additionally it indicates that the session +ticket is in a renewal period and should be replaced. The OpenSSL library will +call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077 +3.3 paragraph 2). + +=item Z<>1 + +This indicates that the I<ctx> and I<hctx> have been set and the session can +continue on those parameters. + +=item Z<>0 + +This indicates that it was not possible to set/retrieve a session ticket and +the SSL/TLS session will continue by by negiotationing a set of cryptographic +parameters or using the alternate SSL/TLS resumption mechanism, session ids. + +If called with enc equal to 0 the library will call the I<cb> again to get +a new set of parameters. + +=item less than 0 + +This indicates an error. + +=back + +=head1 NOTES + +Session resumption shortcuts the TLS so that the client certificate +negiotation don't occur. It makes up for this by storing client certificate +an all other negotiated state information encrypted within the ticket. In a +resumed session the applications will have all this state information available +exactly as if a full negiotation had occured. + +If an attacker can obtain the key used to encrypt a session ticket, they can +obtain the master secret for any ticket using that key and decrypt any traffic +using that session: even if the ciphersuite supports forward secrecy. As +a result applications may wish to use multiple keys and avoid using long term +keys stored in files. + +Applications can use longer keys to maintain a consistent level of security. +For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key +the overall security is only 128 bits because breaking the ticket key will +enable an attacker to obtain the session keys. + +=head1 EXAMPLES + +Reference Implemention: + SSL_CTX_set_tlsext_ticket_key_cb(SSL,ssl_tlsext_ticket_key_cb); + .... + + static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) + { + if (enc) { /* create new session */ + if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) { + return -1; /* insufficient random */ + } + + key = currentkey(); /* something that you need to implement */ + if ( !key ) { + /* current key doesn't exist or isn't valid */ + key = createkey(); /* something that you need to implement. + * createkey needs to initialise, a name, + * an aes_key, a hmac_key and optionally + * an expire time. */ + if ( !key ) { /* key couldn't be created */ + return 0; + } + } + memcpy(key_name, key->name, 16); + + EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + + return 1; + + } else { /* retrieve session */ + key = findkey(name); + + if (!key || key->expire < now() ) { + return 0; + } + + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv ); + + if (key->expire < ( now() - RENEW_TIME ) ) { + /* return 2 - this session will get a new ticket even though the current is still valid */ + return 2; + } + return 1; + + } + } + + + +=head1 RETURN VALUES + +returns 0 to indicate the callback function was set. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_session_reused(3)|SSL_session_reused(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, + +=head1 HISTORY + +This function was introduced in OpenSSL 0.9.8h + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod index 29d1f8a6fbfe..7a27eef50b17 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -12,12 +12,10 @@ SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_se DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); - void SSL_set_tmp_dh_callback(SSL_CTX *ctx, + void SSL_set_tmp_dh_callback(SSL *ctx, DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); long SSL_set_tmp_dh(SSL *ssl, DH *dh) - DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); - =head1 DESCRIPTION SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be @@ -50,12 +48,13 @@ even if he gets hold of the normal (certified) key, as this key was only used for signing. In order to perform a DH key exchange the server must use a DH group -(DH parameters) and generate a DH key. The server will always generate a new -DH key during the negotiation, when the DH parameters are supplied via -callback and/or when the SSL_OP_SINGLE_DH_USE option of -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will -immediately create a DH key, when DH parameters are supplied via -SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case, +(DH parameters) and generate a DH key. +The server will always generate a new DH key during the negotiation +if either the DH parameters are supplied via callback or the +SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both). +It will immediately create a DH key if DH parameters are supplied via +SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. +In this case, it may happen that a key is generated on initialization without later being needed, while on the other hand the computer time during the negotiation is being saved. @@ -81,7 +80,7 @@ instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE is mandatory. Application authors may compile in DH parameters. Files dh512.pem, -dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current +dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current version of the OpenSSL distribution contain the 'SKIP' DH parameters, which use safe primes and were generated verifiably pseudo-randomly. These files can be converted into C code using the B<-C> option of the @@ -141,7 +140,7 @@ partly left out.) dh_tmp = dh_512; break; case 1024: - if (!dh_1024) + if (!dh_1024) dh_1024 = get_dh1024(); dh_tmp = dh_1024; break; diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod index 81566839d3d8..b6ba6bb51cad 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod @@ -109,8 +109,8 @@ certificates would not be present, most likely a X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. The depth count is "level 0:peer certificate", "level 1: CA certificate", "level 2: higher level CA certificate", and so on. Setting the maximum -depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9, -allowing for the peer certificate and additional 9 CA certificates. +depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100, +allowing for the peer certificate and additional 100 CA certificates. The B<verify_callback> function is used to control the behaviour when the SSL_VERIFY_PEER flag is set. It must be supplied by the application and @@ -169,8 +169,8 @@ that will always continue the TLS/SSL handshake regardless of verification failure, if wished. The callback realizes a verification depth limit with more informational output. -All verification errors are printed, informations about the certificate chain -are printed on request. +All verification errors are printed; information about the certificate chain +is printed on request. The example is realized for a server that does allow but not require client certificates. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/crypto/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod index b80e25be7eaa..9da7201a9990 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -81,6 +81,8 @@ SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return Return values from the server callback are interpreted as follows: +=over 4 + =item > 0 PSK identity was found and the server callback has provided the PSK @@ -94,9 +96,11 @@ data to B<psk> and return the length of the random data, so the connection will fail with decryption_error before it will be finished completely. -=item 0 +=item Z<>0 PSK identity was not found. An "unknown_psk_identity" alert message will be sent and the connection setup fails. +=back + =cut diff --git a/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod index cc724c0d561a..22394441741f 100644 --- a/crypto/openssl/doc/ssl/SSL_accept.pod +++ b/crypto/openssl/doc/ssl/SSL_accept.pod @@ -44,17 +44,17 @@ The following return values can occur: =over 4 -=item 1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item 0 +=item Z<>0 The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B<ret> to find out the reason. +=item Z<>1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + =item E<lt>0 The TLS/SSL handshake was not successful because a fatal error occurred either diff --git a/crypto/openssl/doc/ssl/SSL_clear.pod b/crypto/openssl/doc/ssl/SSL_clear.pod index d4df1bfac316..ba192bd518ae 100644 --- a/crypto/openssl/doc/ssl/SSL_clear.pod +++ b/crypto/openssl/doc/ssl/SSL_clear.pod @@ -56,12 +56,12 @@ The following return values can occur: =over 4 -=item 0 +=item Z<>0 The SSL_clear() operation could not be performed. Check the error stack to find out the reason. -=item 1 +=item Z<>1 The SSL_clear() operation was successful. diff --git a/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod index cc56ebb75f3f..68e2b82b8dbb 100644 --- a/crypto/openssl/doc/ssl/SSL_connect.pod +++ b/crypto/openssl/doc/ssl/SSL_connect.pod @@ -41,17 +41,17 @@ The following return values can occur: =over 4 -=item 1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item 0 +=item Z<>0 The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B<ret> to find out the reason. +=item Z<>1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + =item E<lt>0 The TLS/SSL handshake was not successful, because a fatal error occurred either diff --git a/crypto/openssl/doc/ssl/SSL_do_handshake.pod b/crypto/openssl/doc/ssl/SSL_do_handshake.pod index 243576451b7f..b35ddf5f14e1 100644 --- a/crypto/openssl/doc/ssl/SSL_do_handshake.pod +++ b/crypto/openssl/doc/ssl/SSL_do_handshake.pod @@ -45,17 +45,17 @@ The following return values can occur: =over 4 -=item 1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item 0 +=item Z<>0 The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B<ret> to find out the reason. +=item Z<>1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + =item E<lt>0 The TLS/SSL handshake was not successful because a fatal error occurred either diff --git a/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod b/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod index 49fb88f86faf..059376c76b24 100644 --- a/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod +++ b/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod @@ -8,11 +8,11 @@ SSL_get_peer_cert_chain - get the X509 certificate chain of the peer #include <openssl/ssl.h> - STACKOF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); + STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); =head1 DESCRIPTION -SSL_get_peer_cert_chain() returns a pointer to STACKOF(X509) certificates +SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates forming the certificate chain of the peer. If called on the client side, the stack also contains the peer's certificate; if called on the server side, the peer's certificate must be obtained separately using @@ -24,7 +24,7 @@ If the peer did not present a certificate, NULL is returned. The peer certificate chain is not necessarily available after reusing a session, in which case a NULL pointer is returned. -The reference count of the STACKOF(X509) object is not incremented. +The reference count of the STACK_OF(X509) object is not incremented. If the corresponding session is freed, the pointer must not be used any longer. @@ -39,7 +39,7 @@ The following return values can occur: No certificate was presented by the peer or no connection was established or the certificate chain is no longer available when a session is reused. -=item Pointer to a STACKOF(X509) +=item Pointer to a STACK_OF(X509) The return value points to the certificate chain presented by the peer. diff --git a/crypto/openssl/doc/ssl/SSL_get_version.pod b/crypto/openssl/doc/ssl/SSL_get_version.pod index cc271db2c534..9ae6f2550858 100644 --- a/crypto/openssl/doc/ssl/SSL_get_version.pod +++ b/crypto/openssl/doc/ssl/SSL_get_version.pod @@ -12,12 +12,12 @@ SSL_get_version - get the protocol version of a connection. =head1 DESCRIPTION -SSL_get_cipher_version() returns the name of the protocol used for the +SSL_get_version() returns the name of the protocol used for the connection B<ssl>. =head1 RETURN VALUES -The following strings can occur: +The following strings can be returned: =over 4 @@ -31,7 +31,15 @@ The connection uses the SSLv3 protocol. =item TLSv1 -The connection uses the TLSv1 protocol. +The connection uses the TLSv1.0 protocol. + +=item TLSv1.1 + +The connection uses the TLSv1.1 protocol. + +=item TLSv1.2 + +The connection uses the TLSv1.2 protocol. =item unknown diff --git a/crypto/openssl/doc/ssl/SSL_read.pod b/crypto/openssl/doc/ssl/SSL_read.pod index 7038cd2d7520..8ca0ce5058da 100644 --- a/crypto/openssl/doc/ssl/SSL_read.pod +++ b/crypto/openssl/doc/ssl/SSL_read.pod @@ -86,7 +86,7 @@ The following return values can occur: The read operation was successful; the return value is the number of bytes actually read from the TLS/SSL connection. -=item 0 +=item Z<>0 The read operation was not successful. The reason may either be a clean shutdown due to a "close notify" alert sent by the peer (in which case diff --git a/crypto/openssl/doc/ssl/SSL_session_reused.pod b/crypto/openssl/doc/ssl/SSL_session_reused.pod index da7d06264d04..b09d8a71b062 100644 --- a/crypto/openssl/doc/ssl/SSL_session_reused.pod +++ b/crypto/openssl/doc/ssl/SSL_session_reused.pod @@ -27,11 +27,11 @@ The following return values can occur: =over 4 -=item 0 +=item Z<>0 A new session was negotiated. -=item 1 +=item Z<>1 A session was reused. diff --git a/crypto/openssl/doc/ssl/SSL_set_fd.pod b/crypto/openssl/doc/ssl/SSL_set_fd.pod index 70291128fcec..14808716055d 100644 --- a/crypto/openssl/doc/ssl/SSL_set_fd.pod +++ b/crypto/openssl/doc/ssl/SSL_set_fd.pod @@ -35,11 +35,11 @@ The following return values can occur: =over 4 -=item 0 +=item Z<>0 The operation failed. Check the error stack to find out why. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_set_session.pod b/crypto/openssl/doc/ssl/SSL_set_session.pod index 5f54714ad86a..197b5218305b 100644 --- a/crypto/openssl/doc/ssl/SSL_set_session.pod +++ b/crypto/openssl/doc/ssl/SSL_set_session.pod @@ -37,11 +37,11 @@ The following return values can occur: =over 4 -=item 0 +=item Z<>0 The operation failed; check the error stack to find out the reason. -=item 1 +=item Z<>1 The operation succeeded. diff --git a/crypto/openssl/doc/ssl/SSL_set_shutdown.pod b/crypto/openssl/doc/ssl/SSL_set_shutdown.pod index 011a022a12c3..fe013085d39d 100644 --- a/crypto/openssl/doc/ssl/SSL_set_shutdown.pod +++ b/crypto/openssl/doc/ssl/SSL_set_shutdown.pod @@ -24,7 +24,7 @@ The shutdown state of an ssl connection is a bitmask of: =over 4 -=item 0 +=item Z<>0 No shutdown setting, yet. diff --git a/crypto/openssl/doc/ssl/SSL_shutdown.pod b/crypto/openssl/doc/ssl/SSL_shutdown.pod index 89911acbcac8..85d4a64b03f9 100644 --- a/crypto/openssl/doc/ssl/SSL_shutdown.pod +++ b/crypto/openssl/doc/ssl/SSL_shutdown.pod @@ -92,18 +92,18 @@ The following return values can occur: =over 4 -=item 1 - -The shutdown was successfully completed. The "close notify" alert was sent -and the peer's "close notify" alert was received. - -=item 0 +=item Z<>0 The shutdown is not yet finished. Call SSL_shutdown() for a second time, if a bidirectional shutdown shall be performed. The output of L<SSL_get_error(3)|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. + =item -1 The shutdown was not successful because a fatal error occurred either diff --git a/crypto/openssl/doc/ssl/SSL_write.pod b/crypto/openssl/doc/ssl/SSL_write.pod index e013c12d5254..a57617f3ee9a 100644 --- a/crypto/openssl/doc/ssl/SSL_write.pod +++ b/crypto/openssl/doc/ssl/SSL_write.pod @@ -79,7 +79,7 @@ The following return values can occur: The write operation was successful, the return value is the number of bytes actually written to the TLS/SSL connection. -=item 0 +=item Z<>0 The write operation was not successful. Probably the underlying connection was closed. Call SSL_get_error() with the return value B<ret> to find out, diff --git a/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod index 81d276477f9f..bce06e23b619 100644 --- a/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod +++ b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod @@ -48,6 +48,16 @@ known limit on the size of the created ASN1 representation, so the necessary amount of space should be obtained by first calling i2d_SSL_SESSION() with B<pp=NULL>, and obtain the size needed, then allocate the memory and call i2d_SSL_SESSION() again. +Note that this will advance the value contained in B<*pp> so it is necessary +to save a copy of the original allocation. +For example: + int i,j; + char *p, *temp; + i = i2d_SSL_SESSION(sess, NULL); + p = temp = malloc(i); + j = i2d_SSL_SESSION(sess, &temp); + assert(i == j); + assert(p+i == temp); =head1 RETURN VALUES |